Skip to content
Find file
Fetching contributors…
Cannot retrieve contributors at this time
9447 lines (7772 sloc) 413 KB
\input texinfo
@c %**start of header
@setfilename paxutils.info
@settitle pax Utilities
@c %**end of header
@c ======================================================================
@c This document has three levels of rendition: PUBLISH, DISTRIB or PROOF,
@c as decided by @set symbols. The PUBLISH rendition tries to be clean.
@c Most users prefer more information, even if it is not fully revised,
@c so DISTRIB is the default for tar distributions. The PROOF rendition
@c also shows all FIXMEs, for when we work on the manual.
@c ======================================================================
@ifclear PUBLISH
@ifclear DISTRIB
@ifclear PROOF
@set DISTRIB
@end ifclear
@end ifclear
@end ifclear
@ifset PUBLISH
@smallbook
@set RENDITION The book, version
@end ifset
@ifset DISTRIB
@finalout
@set RENDITION FTP release, version
@end ifset
@ifset PROOF
@finalout
@set RENDITION Proofreading edition
@end ifset
@macro FIXME{string}
@allow-recursion
@quote-arg
@ifset PROOF
@strong{<FIXME>} \string\ @strong{</>}
@end ifset
@end macro
@set absolute-names @w{@kbd{--absolute-names}} (@kbd{-P})
@set after-date @w{@kbd{--after-date=@var{date}}} (@w{@kbd{--newer=@var{date}}}, @kbd{-N @var{date}})
@set append @w{@kbd{--append}} (@kbd{-r})
@set atime-preserve @w{@kbd{--atime-preserve}}
@set backup @w{@kbd{--backup}[=@var{method}]}
@set block-number @w{@kbd{--block-number}} (@kbd{-R})
@set blocking-factor @w{@kbd{--blocking-factor=@var{blocks}}} (@kbd{-b @var{blocks}})
@set checkpoint @w{@kbd{--checkpoint}}
@set compare @w{@kbd{--compare}} (@w{@kbd{--diff}}, @kbd{-d})
@set compress @w{@kbd{--compress}} (@kbd{-Z})
@set concatenate @w{@kbd{--concatenate}} (@w{@kbd{--catenate}}, @kbd{-A})
@set create @w{@kbd{--create}} (@kbd{-c})
@set delete @w{@kbd{--delete}}
@set dereference @w{@kbd{--dereference}} (@kbd{-h})
@set directory @w{@kbd{--directory=@var{directory}}} (@kbd{-C @var{directory}})
@set exclude @w{@kbd{--exclude=@var{pattern}}}
@set exclude-from @w{@kbd{--exclude-from=@var{file-of-patterns}}} (@kbd{-X @var{file-of-patterns}})
@set extract @w{@kbd{--extract}} (@w{@kbd{--get}}, @kbd{-x})
@set file @w{@kbd{--file=@var{archive-name}}} (@kbd{-f @var{archive-name}})
@set files-from @w{@kbd{--files-from=@var{file-of-names}}} (@kbd{-T @var{file-of-names}})
@set force-local @w{@kbd{--force-local}}
@set group @w{@kbd{--group=@var{group}}}
@set gzip @w{@kbd{--gzip}} (@kbd{-z})
@set help @w{@kbd{--help}}
@set ignore-failed-read @w{@kbd{--ignore-failed-read}}
@set ignore-zeros @w{@kbd{--ignore-zeros}} (@kbd{-i})
@set incremental @w{@kbd{--incremental}} (@kbd{-G})
@set info-script @w{@kbd{--info-script=@var{script-name}}} (@w{@kbd{--new-volume-script=@var{script-name}}}, @kbd{-F @var{script-name}})
@set interactive @w{@kbd{--interactive}} (@w{@kbd{--confirmation}}, @kbd{-w})
@set keep-old-files @w{@kbd{--keep-old-files}} (@kbd{-k})
@set label @w{@kbd{--label=@var{archive-label}}} (@kbd{-V @var{archive-label}})
@set list @w{@kbd{--list}} (@kbd{-t})
@set listed-incremental @w{@kbd{--listed-incremental=@var{snapshot-file}}} (@kbd{-g @var{snapshot-file}})
@set mode @w{@kbd{--mode=@var{permissions}}}
@set multi-volume @w{@kbd{--multi-volume}} (@kbd{-M})
@set name-prefix @w{@kbd{--name-prefix=@var{prefix}}}
@set newer-mtime @w{@kbd{--newer-mtime=@var{date}}}
@set no-attributes @w{@kbd{--no-attributes}}
@set no-recursion @w{@kbd{--no-recursion}}
@set null @w{@kbd{--null}}
@set numeric-owner @w{@kbd{--numeric-owner}}
@set old-archive @w{@kbd{--old-archive}} (@kbd{-o})
@set one-file-system @w{@kbd{--one-file-system}} (@kbd{-l})
@set owner @w{@kbd{--owner=@var{user}}}
@set posix @w{@kbd{--posix}}
@set quick @w{@kbd{--quick}}
@set preserve @w{@kbd{--preserve}}
@set read-full-records @w{@kbd{--read-full-records}} (@kbd{-B})
@set record-size @w{@kbd{--record-size=@var{size}}}
@set recursive-unlink @w{@kbd{--recursive-unlink}}
@set remove-files @w{@kbd{--remove-files}}
@set rsh-command @kbd{rsh-command=@var{command}}
@set same-order @w{@kbd{--same-order}} (@w{@kbd{--preserve-order}}, @kbd{-s})
@set same-owner @w{@kbd{--same-owner}}
@set same-permissions @w{@kbd{--same-permissions}} (@w{@kbd{--preserve-permissions}}, @kbd{-p})
@set show-omitted-dirs @w{@kbd{--show-omitted-dirs}}
@set sparse @w{@kbd{--sparse}} (@kbd{-S})
@set starting-file @w{@kbd{--starting-file=@var{name}}} (@kbd{-K @var{name}})
@set suffix @w{@kbd{--suffix=@var{suffix}}}
@set tape-length @w{@kbd{--tape-length=@var{KBytes}}} (@kbd{-L @var{KBytes}})
@set to-stdout @w{@kbd{--to-stdout}} (@kbd{-O})
@set totals @w{@kbd{--totals}}
@set touch @w{@kbd{--touch}} (@kbd{-m})
@set unlink-first @w{@kbd{--unlink-first}} (@kbd{-U})
@set update @w{@kbd{--update}} (@kbd{-u})
@set use-compress-program @w{@kbd{--use-compress-program=@var{program}}}
@set verbose @w{@kbd{--verbose}} (@kbd{-v})
@set verify @w{@kbd{--verify}} (@kbd{-W})
@set version @w{@kbd{--version}}
@set volno-file @w{@kbd{--volno-file=@var{file-of-number}}}
@include version.texi
@c Put everything in one index (arbitrarily chosen to be the concept index).
@syncodeindex fn cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex vr cp
@defindex op
@syncodeindex op cp
@ifinfo
@format
START-INFO-DIR-ENTRY
* pax utilities: (paxutils). pax and other archiving utilities.
* cpio: (paxutils)cpio invocation. Handling cpio archives.
* pax: (paxutils)pax invocation. The POSIX archiver.
* tar: (paxutils)tar invocation. Making tape (or disk) archives.
* mt: (paxutils)mt invocation. Basic tape positioning.
* rmt: (paxutils)rmt invocation. The remote tape facility.
END-INFO-DIR-ENTRY
@end format
@end ifinfo
@ifinfo
This file documents @code{paxutils} @value{VERSION}.
Copyright (C) 1992, 1994, 1995, 1996, 1997, 1998 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).
@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
@end ifinfo
@setchapternewpage odd
@shorttitlepage @code{pax} Utilities
@titlepage
@title pax Utilities
@subtitle @value{RENDITION} @value{VERSION}, @value{UPDATED}
@author John Gilmore and others
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1998 Free Software
Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Free Software Foundation.
@end titlepage
@c @ifinfo
@node Top, Introduction, (dir), (dir)
@top
This file documents @code{pax} utilities. @code{cpio}, @code{pax}
and @code{tar} are tools used to store, backup, and transport files
within archives. These tools are able to create and extract archives.
@code{cpio} is also able to directly copy many files from one place to
another. Some accessory tools allow to do basic tape positionning and
handling, either locally or remotely.
Most of the manual, as it stands, specifically describes @code{tar}.
This comes from the fact that it results from a quick merge of a small
@code{cpio} document within a relatively bigger @code{tar} manual. It also
account for the fact that @code{tar} is currently much more complex than
the other tools. We expect that such things might tend to reequilibrate
themselves, as time and maintenance goes, as the tools in @code{pax}
utilities will influence each other.
This manual documents the release @value{VERSION} of @code{pax} utilities.
@menu
* Introduction:: Introduction
* cpio Tutorial:: Tutorial introduction to @code{cpio}
* tar Tutorial:: Tutorial introduction to @code{tar}
* cpio invocation:: Invoking @code{cpio}
* pax invocation:: Invoking @code{pax}
* tar invocation:: Invoking @code{tar}
* Subcommands:: @code{tar} subcommands
* Choosing:: Choosing files and names for @code{tar}
* Formats:: Controlling the archive format
* Media:: Tapes and other archive media
* Backups:: Performing backups and restoring files
* All options:: All @code{tar} options
* Date input formats:: Date input formats
* Archive format:: Format of archive files
* Index:: Index
@detailmenu
--- The Detailed Node Listing ---
Introduction
* Book contents:: What this book contains
* Definitions:: Some definitions
* What cpio does:: What @code{cpio} does
* What pax does:: What @code{pax} does
* What tar does:: What @code{tar} does
* Stylistic conventions:: Stylistic conventions
* Authors:: @code{tar} authors
* Reports:: Reporting bugs or suggestions
Tutorial Introduction to @code{tar}
* Assumptions:: Assumptions this tutorial makes
* Simplified invokation:: The structure of a @code{tar} command
* Basic tar options:: @code{tar} subcommands and options
* create list extract tutorial:: The three most frequently used subcommands
* file verbose help:: Three frequently used options
* create tutorial:: How to create archives
* list tutorial:: How to list archives
* extract tutorial:: How to extract members from an archive
* Looking ahead:: Looking ahead: The rest of this manual
Three Frequently Used Options
* file tutorial:: The @kbd{--file} option
* verbose tutorial:: The @kbd{--verbose} option
* help tutorial:: Getting help: Using the @kbd{--help} option
How to Create Archives
* prepare for examples:: Preparing a practice directory for examples
* Creating the archive tutorial:: Creating the archive
* create verbose:: Running @kbd{--create} with @kbd{--verbose}
* Short create:: Short forms with @kbd{--create}
* create dir tutorial:: Archiving directories
How to List Archives
* absolute tutorial:: Specifying member names correctly
* Listing directories:: Listing the contents of a stored directory
How to Extract Members from an Archive
* Extracting archives:: Extracting an entire archive
* Extracting files:: Extracting specific files
* Extracting directories:: Extracting files that are directories
* Failing commands:: Commands that will fail
* Two mistakes:: Two dangerous mistakes
Invoking @code{cpio}
* Copy-out mode:: Copy-out mode
* Copy-in mode:: Copy-in mode
* Copy-pass mode:: Copy-pass mode
* cpio Options:: Options for @code{cpio}
Invoking @code{tar}
* Synopsis:: General synopsis of @code{tar}
* Using options:: Using @code{tar} options
* Styles:: The three option styles
* Documentation and help:: Documentation and troubleshooting
* interactive:: Asking for confirmation during subcommands
The Three Option Styles
* Long options:: Long option style
* Short options:: Short option style
* Old style:: Old option style
* Mixing:: Mixing option styles
Documentation and Troubleshooting
* version:: Knowing the @code{tar} version
* help:: Getting help: Using the @kbd{--help} option
* verbose:: The @kbd{--verbose} option
* checkpoint:: Being warned of all directories
* show-omitted-dirs:: Being warned of skipped directories
* totals:: Sizeing the amount of data written
* block-number:: Adding physical addresses to messages
@code{tar} Subcommands
* list:: How to list archives
* extract:: How to extract members from an archive
* create:: The three most frequently used subcommands
* Applications:: Other uses for @code{tar}
How to List Archives
* Reading:: Options to help read archives
* compare:: Comparing members with the file system
Options to Help Read Archives
* read-full-records:: Reading full records
* ignore-zeros:: Ignoring blocks of zeros
* ignore-failed-read:: Ignoring read failures
How to Extract Members from an Archive
* extract options:: Options used for extraction
* Writing:: Changing how @code{tar} writes files
* Preventing overwrite:: Options to prevent overwriting files
* Unlinking:: Options to destroy files
* Attributes:: Handling file attributes
* Scarce:: Coping with scarce resources
Options to Prevent Overwriting Files
* keep-old-files:: Keeping old files
* to-stdout:: Writing to standard output
* backup:: Backup options
* suffix:: Deciding the backup file suffixes
Options to Destroy Files
* unlink-first:: Removing files prior to extraction
* recursive-unlink:: Removing whole directories
Handling File Attributes
* touch:: Setting modification times
* same-owner:: Restoring file ownership
* same-permissions:: Setting access permissions
* no-attributes:: Leaving file attributes alone
Coping with Scarce Resources
* starting-file:: Starting file
* same-order:: Same order
* preserve:: Preserving permissions and order
How to Create Archives
* name-prefix:: Using name prefixes
* atime-preserve:: Preserving last access time
* remove-files:: Removing files
* append:: How to add files to existing archives
* update:: Updating an archive
How to Add Files to Existing Archives
* Appending files:: Appending files to an archive
* Multiple files:: Multiple files with the same name
Updating an Archive
* How to update:: How to update members of an archive
* Unsuitability of update:: Updating does not always work
Other @code{tar} Usages
* concatenate:: Combining archives with @code{tar}
* Using cat with archives:: Combining archives with @code{cat}
* delete:: Removing archive members from an archive
Combining Archives with @code{tar}
* Using cat with archives:: Combining archives with @code{cat}
Choosing Files and Names for @code{tar}
* file:: Three frequently used options
* Selecting Archive Members:: Selecting archive members
* Exclusions:: Excluding files by name
* Time criteria:: Time based exclusions
* Walking:: Walking through directories
* Relative:: Relative notations for file names
Choosing and Naming Archive Files
* Using file:: Using the @kbd{--file} option
* Standard archive:: Archive on standard input or output
* lmh:: Abbreviating drive and density
* Remote:: Accessing a remote drive
* force-local:: Inhibiting remote access
* rsh-command:: Selecting the remote access mechanism
* rmt invocation:: How @code{rmt} works
Selecting Archive Members
* files-from:: Reading names from a file
* find with files-from:: Using @code{find} to generate a list of files
* null:: @code{NUL} terminated file names
Excluding Files by Name
* exclude:: Excluding some files
* exclude-from:: Handling a lot of exclusions
* Wildcards:: Wildcard patterns and matching
* Problems with exclude:: Problems with using the @code{exclude} options
Time Based Exclusions
* after-date:: Operating only on new files
* newer-mtime:: Operating only on altered files
Walking through Directories
* no-recursion:: Descending into directories
* one-file-system:: Crossing filesystem boundaries
Relative Notations for File Names
* directory:: Changing the working directory
* absolute-names:: Absolute file names
Controlling the Archive Format
* Portability:: Making @code{tar} archives more portable
* Forced fields:: Options to preset file attributes
* Compression:: Using less space through compression
* Other formats:: Other non-@code{tar} formats
Making @code{tar} Archives More Portable
* Portable names:: Portable names
* dereference:: Symbolic links
* old-archive:: Old V7 archives
* posix:: @code{tar} and POSIX @code{tar}
* Checksumming:: Checksumming problems
Options to Preset File Attributes
* mode:: Presetting permissions
* owner:: Forcing a given owner
* group:: Forcing a given group
* numeric-owner:: Using numeric owner and group
Using Less Space through Compression
* Archive compression:: Compressing the whole archive
* Member compression:: Compressing individual members
Compressing the Whole Archive
* gzip:: Using @code{gzip} compression
* compress:: Using @code{compress} compression
* use-compress-program:: Using other compression programs
Compressing Individual Members
* sparse:: Archiving sparse files
Other non-@code{tar} formats
* cpio:: Tutorial introduction to @code{cpio}
* zip:: Comparison of @code{tar} and @code{zip}
Tapes and Other Archive Media
* Blocking:: Blocking
* Many on one:: Many archives on one tape
* One on many:: Using multiple tapes
* Being careful:: Being even more careful
* Other tape considerations:: Other tape considerations
Blocking
* Blocks and records:: Blocks and records
* blocking-factor:: Setting the blocking factor
* record-size:: Setting a record size
* Media types:: Per-Media blocking considerations
* Reblocking:: Automatic reblocking
Many Archives on One Tape
* Tape positioning:: Tape positions and tape marks
* mt invocation:: The @code{mt} utility
Using Multiple Tapes
* Multi-volume archives:: Archives longer than one tape or disk
* multi-volume:: Using multi-volume mode
* tape-length:: Announcing the tape length
* info-script:: Taking actions at volume switching
* volno-file:: Changing the volume number in prompts
Being Even More Careful
* label:: Including labels in the archive
* verify:: Verifying data as it is stored
* Write protection:: Write protection
Performing Backups and Restoring Files
* incremental listed-incremental:: The incremental options
* 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
The Incremental Options
* incremental:: The incremental options
* listed-incremental:: Backing up with a snapshot list
Levels of Backups
* Full dumps:: Using @code{tar} to perform full dumps
* Incremental dumps:: Using @code{tar} to perform incremental dumps
Setting Parameters for Backups and Restoration
* backup-specs example:: An example text of @file{backup-specs}
* Script syntax:: Syntax for @file{backup-specs}
All @code{tar} Options
* Subcommand summary:: Subcommands
* Option summary:: @code{tar} options
* Short option summary:: Short options cross-reference
Date Input Formats
* General date syntax:: General date syntax
* Calendar date item:: Calendar date item
* Time of day item:: Time of day item
* Timezone item:: Timezone item
* Day of week item:: Day of week item
* Relative item in date strings:: Relative item in date strings
* Pure numbers in date strings:: Pure numbers in date strings
* Authors of getdate:: Authors of @code{getdate}
Format of Archive Files
* tar-h:: The C description of a header block
* Standard format:: The standard format
* Extended format:: Extensions to the archive format
@end detailmenu
@end menu
@c @end ifinfo
@node Introduction, cpio Tutorial, Top, Top
@chapter Introduction
Welcome to the @code{pax} Utilities manual. Most tools in this collection
are used to create and manipulate files (@dfn{archives}), which are actually
collections of many other files. The utilities provide users with an
organized and systematic method for controlling a large amount of data.
Other tools are meant to manoeuvre magnetic tapes.
@menu
* Book contents:: What this book contains
* Definitions:: Some definitions
* What cpio does:: What @code{cpio} does
* What pax does:: What @code{pax} does
* What tar does:: What @code{tar} does
* Stylistic conventions:: Stylistic conventions
* Authors:: @code{tar} authors
* Reports:: Reporting bugs or suggestions
@end menu
@node Book contents, Definitions, Introduction, Introduction
@section What this book contains
This chapter introduces you to various terms that will recur throughout the
book. It also tells you who has worked on @code{tar} and its documentation,
and where you should send bug reports or comments.
The second chapter is a tutorial (@pxref{tar Tutorial}) which provides a
gentle introduction for people who are new to using @code{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. The tutorial introduces the
three most frequently used subcommands (@value{create}, @value{list},
and @value{extract}) as well as a few frequently used options.
Each remaining chapter presents everything that needs to be said about
a specific topic. These, taken altogether, should offer a complete
reference manual for @code{tar} (they do not refer to the tutorial chapter).
The entire book, including the tutorial, assumes that the reader understands
some basic concepts of using a Unix-type operating system.
The third chapter presents @code{tar} options and option syntax. The fourth
chapter presents all @code{tar} subcommands, as well as many options more
specifically related to particular @code{tar} subcommands. Other chapters
explain how one chooses files and entry names on which @code{tar} operates
and how one selects the format and portability of generated
archives. The final chapters concentrate on magnetic media used for archiving,
and discuss how backups can be generated and restored.
One appendix (@pxref{Date input formats}) exists in its entirety in
other GNU manuals, and is mostly self-contained. Another appendix
(@pxref{Archive format}), which details the format of the archive file
generated by @code{tar}, contains a long quotation taken directly from the
@code{tar} sources.
@node Definitions, What cpio does, Book contents, Introduction
@section Some definitions
@cindex archive
@cindex tar archive
The @code{tar} program is used to create and manipulate @code{tar}
archives. An @dfn{archive} is a single file which contains the contents
of many files, while still identifying the name of each file, its
owner, and so forth.@footnote{In addition, archives record access
permissions, user and group, size in bytes, and last modification time.
Some archives also record the file names in each archived directory, as
well as other file and directory information.} You can use @code{tar}
to @dfn{create} a new archive in a specified directory.
@cindex member
@cindex archive member
@cindex file name
@cindex member name
The files inside an archive are called @dfn{members}. Within this
manual, we use the term @dfn{file} to refer only to files accessible in
the normal ways (by @code{ls}, @code{cat}, and so forth), and the term
@dfn{member} to refer only to the members of an archive. Similarly, a
@dfn{file name} is the name of a file, as it resides in the filesystem,
and a @dfn{member name} is the name of an archive member within the
archive.
@cindex extraction
@cindex unpacking
The term @dfn{extraction} refers to the process of copying an archive
member (or multiple members) into in the filesystem as a file (or files). Extracting
all the members of an archive is often called @dfn{extracting the
archive}. The term @dfn{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 @dfn{list} the members in a given archive
(this is often thought of as ``printing'' them to the standard output,
or the command line), or @dfn{append} members to a pre-existing archive.
All of these tasks can be performed using @code{tar} subcommands.
@node What cpio does, What pax does, Definitions, Introduction
@section What @code{cpio} does
@cindex cpio
The @code{cpio} program copies files into or out of a @code{cpio}
or @code{tar} archive. The archive can be another file on the disk,
a magnetic tape, or a pipe.
@code{cpio} supports the following archive formats: binary, old ASCII,
new ASCII, crc, HPUX binary, HPUX old ASCII, old @code{tar}, and POSIX.1
@code{tar}. The @code{tar} format is provided for compatibility with the
@code{tar} program. By default, @code{cpio} creates binary format archives,
for compatibility with older @code{cpio} programs. When extracting from
archives, @code{cpio} automatically recognizes which kind of archive it
is reading and can read archives created on machines with a different
byte-order.
@node What pax does, What tar does, What cpio does, Introduction
@section What @code{pax} does
@cindex pax
The @code{pax} program is the archiving utility specified and mandated by
POSIX. It handles @code{cpio} or @code{tar} archives, using a different
user interface. This program is not really available yet in @code{pax}
utilities: it only received little testing so far, and some required
functionnalities are still to be written.
@node What tar does, Stylistic conventions, What pax does, Introduction
@section What @code{tar} does
@cindex tar
The @code{tar} program allows the creation of @code{tar}
archives, as well as various other kinds of manipulation. For example,
you can use @code{tar} on previously created archives to extract files,
to store additional files, or to update or list files which were already
stored.
Initially, @code{tar} archives were used to store files conveniently on
magnetic tape. The name @samp{tar} comes from this use; it stands for
@strong{t}ape @strong{ar}chiver. Despite the utility's name, @code{tar}
can direct its output to other available devices, files, or other programs (using
pipes). @code{tar} can even access remote devices or files (as archives).
You can use @code{tar} archives in many ways. We want to stress a few
of them: storage, backup, and transportation.
@table @asis
@item Storage
Often, @code{tar} archives are used to store related files for convenient
file transfer over a network. While preparing it for distribution, software
is often bundled into @code{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 @code{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 @code{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 @code{tar} can be used to move archives in
all dimensions, even time!)
@item Backup
Because the archive created by @code{tar} is capable of preserving file
information and directory structure, @code{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. @code{tar} has
special features that allow it to be used to make incremental and full
dumps of all the files in a filesystem.
@item 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.
@end table
@node Stylistic conventions, Authors, What tar does, Introduction
@section Stylistic conventions
Conventionally, @code{tar} archives are given names ending with
@samp{.tar}. This is not necessary for @code{tar} to operate properly,
but this manual follows that convention in order to accustom readers to
it and to make examples clearer.
@cindex tar file
@cindex entry
@cindex tar entry
Often, people refer to @code{tar} archives as ``@code{tar} files'', and
archive members as ``files'' or ``entries''. For people familiar with
the operation of @code{tar}, this causes no difficulty. However, in
this manual, we consistently refer to ``archives'' and ``archive
members'' to make learning to use @code{tar} easier for novice users.
@iftex
In the examples, @samp{$} represents a typical shell prompt. It precedes
lines you should type; to make this more clear, any text meant to be
written by you is shown in @kbd{this font}, as opposed to lines which
represent the computer's response; those lines are shown in @code{this
font}, or sometimes @samp{like this}.
@end iftex
@ifinfo
In the examples, @samp{$} represents a typical shell prompt. It
precedes lines you should type; to make this more clear, those lines as
well as the lines which represent the computer's response are shown in
@kbd{like this}.
@end ifinfo
Although long option names are more easily learned and read, short options
are still so widely used that we cannot ignore them. So that you can become
familiar with both styles at once, this manual usually repeats both the long
(mnemonic) and short (abbreviated) option names whenever referring them,
as well as within examples. Many options do not have a short version.
@node Authors, Reports, Stylistic conventions, Introduction
@section @code{tar} authors
The @code{tar} program in @code{paxutils} evolved out of a project
originally written and maintained by John Gilmore (under
the name @w{@code{PD TAR}}). The project started in 1985-08, and was offered
to the FSF in 1985-09 with the agreement that later FSF contributions
to @w{@code{PD TAR}} were to be public domain rather than copylefted.
The result was posted to @file{mod.sources} in 1986-10. This version
had the three main subcommands (old and short style options), supported
both V7 format and a draft of P1003, archive compression, remote dumps
(using @w{@code{rsh dd}} instead of @code{rmt}), big blocking, and clean
end-of-file blocks, and was designed to be fast. Written and initially
debugged on a Sun Workstation running 4.2BSD, @w{@code{PD TAR}} was
soon ported to Xenix, Unisoft, Vax 4.2BSD, utzoonix, USG, Masscomp,
Minix, and MS-DOS systems (VMS, Mac, Atari, and Amiga were added later).
Another version was posted to @file{comp.sources.unix} in 1987-11, and
was presented on the Sun User Group in 1987-12 as @code{sugtar}.
In 1988-02, the FSF asked Jay Fenlason to implement arbitrarily long file
names, append and update subcommands, multi-volume
support, and verify and backup features. After having received John's
permission to do so in 1988-09, the FSF published a forked, copylefted
version named @code{gnutar} in 1990-01. While @w{@code{PD TAR}}
continued to evolve
in parallel, unidentified derivatives were distributed separately without
sources, to the point that John decided in 1992-01, as a maintainer, that
the public domain status of @w{@code{PD TAR}} was @emph{unfortunate}.
In 1992-05, John wrote that it had been a mistake. Later, in 1994-11, John
suggested that we merge @w{@code{PD TAR}} definitively into @code{gnutar}.
The sparse file processing in @code{tar}, added for the FSF by Joy Kendall
(1989-06 to 1989-08), has been the subject of much debate, as it directly
conflicts with the POSIX @code{prefix} field.@footnote{In 1988-03, Jay
Fenlason was notified of the impending existence of this @code{prefix}
field. As J@"org Schilling (the @code{star} author)
once put it: @cite{I would call this a hard violation of the standard.}}
The FSF package has been maintained by Jay Fenlason (1988-02 to 1991-01) and
Michael Bushnell@footnote{In 1992, an enthusiastic teacher and his students
promised a new @code{tar} to the FSF, including curses, Athena and Motif
interfaces, wholly automated archives, multi-platform parallel tapes, all
backup formats, etc. The FSF got totally seduced, and stopped all @code{tar}
development and most maintenance while waiting for the Wonder, which of
course, never came.} (1991-01 to 1993-03), with occasional interventions
from David J. MacKenzie. Since 1994-06, Fran@,{c}ois Pinard has been maintaining it
with the help of numerous and kind users. Let me stress that @code{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 only partial, list of those contributors
can be found in the @file{THANKS} file from the @code{tar} distribution.
Jay Fenlason put together a draft of a @code{tar} manual, borrowing notes
from the original @code{man} page from John Gilmore. This draft was
distributed in @code{tar} versions 1.04 through 1.10, then withdrawn in
version 1.11, for Michael Bushnell and Amy Gorin to work on a revamped
version meant for the FSF, including a tutorial. For version 1.11.8,
Fran@,{c}ois Pinard put a manual together by merging information from
all these sources. For the FSF, Melissa Weisshaus later started an
overhaul of the manual, and so did Daniel Hagerty. Another merge yielded
the manual you are now reading. People contributed to specific aspects,
like Karl Berry for dates, @FIXME{Dan Hagerty for backups,} Eli Zaretskii
for MS-DOS, and surely others. The title page of this manual
was once a bit crowded with too many authors, so I (Fran@,{c}ois)
decided for simplicity. The title page now bears the sole name of John
Gilmore. I chose to pay that simple tribute to John's involvement behind
the existence of this @code{tar}.@footnote{Readers often infer the author
of a program from the author of its manual. The current distribution, and
even its documentation, is still in the spirit of the original @w{@code{PD
TAR}} incentive. So, although many people contributed, John Gilmore remains
the real spiritual author for this package.}
The @code{cpio} program included in @code{paxutils} has been originally
written by Phil Nelson in the summer of 1988, and further maintained by
David MacKenzie up to 1992-11. John Oleynick took over the @code{cpio}
distribution until 1996-01. Tom Tromey worked on @code{cpio} from 1995-10
until 1998-05, that is, until it was merged with @code{tar} to create this
@code{paxutils} package. The parts of this manual pertaining to @code{cpio},
including the @code{cpio} tutorial, have been written by Robert Carleton.
The @code{pax} program was added to the @code{cpio} distribution by Tom
Tromey in 1995-10, and was brought into @code{paxutils} together with
@code{cpio} and @code{mt}.
@node Reports, , Authors, Introduction
@section Reporting bugs or suggestions
@cindex bug reports
@cindex reporting bugs
If you find problems or have suggestions about this program or manual,
please report them to @email{paxutils-bugs@@iro.umontreal.ca}.@footnote{Even
though John Gilmore is the original author of @code{tar}, as he is no
longer actively involved in its maintenance, he now prefers to be left
out of @code{paxutils}-related email.} You may also write directly, and less
officially, to @email{pinard@@iro.umontreal.ca}. However, be warned that
bug reports are public by nature; they may be transmitted to other
maintainers or read by people interested in @code{tar} development.
A good bug report precisely explains your input, what you expected, what
you got, and why this is wrong: in fact, it should help us (that is,
the maintainer and those helping him) to see through your eyes. If you
think it might be useful, also send the necessary files and a recipe
for reproducing the problem, carefully explaining what we should look at
and understand. Even though we prefer small files, large files are sometimes
necessary; please make special, prior arrangements with us in such cases.
Be aware that some mailers mangle data, so @code{uuencode}, @code{shar},
or MIME methods are usually required.
You may expect an acknowledgement for your report soon after we receive it,
and then some more information later, after we have worked on it. Due to
the difficult nature of many problems and the general work overload, it may take
a long while before you get a definitive reply. The @file{BACKLOG} file,
in the distribution, summarizes all pending mail and reports about @code{tar}.
Even though we prefer reports about the latest version of @code{tar}, this is
not a strict requirement. The command @kbd{tar --version} should tell you
which version you have. The canonical distribution points for the version
documented in this manual, and the main GNU copy of this distribution, are:
@example
ftp://ftp.iro.umontreal.ca/pub/tar/tar-@value{VERSION}.tar.gz
ftp://ftp.gnu.org/pub/gnu/tar-@value{VERSION}.tar.gz
@end example
@noindent
You can also get @code{tar} from the numerous GNU mirrors around the world.
At the canonical distribution point, you might sometimes stumble on
prereleases (which should normally not have a GNU copy). Pretest releases
always have a letter suffixing the version numbers. Please do @emph{not}
redistribute these, as they are meant for pretesting only. You ought to
understand that prereleases might not be as stable as true releases, and
that problems may be expected with them. You may fetch pretest releases,
of course, but then, you should understand the collaborative spirit of
pretesting.
@node cpio Tutorial, tar Tutorial, Introduction, Top
@chapter Tutorial introduction to @code{cpio}
@cindex creating a cpio archive
@cindex extracting a cpio archive
@cindex copying directory structures
@cindex passing directory structures
The @code{cpio} program performs three primary functions. Copying files to
an archive, extracting files from an archive, and passing files to another
directory tree. An archive can be a file on disk, one or more floppy disks,
or one or more tapes.
When creating an archive, @code{cpio} takes the list of files to be processed
from the standard input, and then sends the archive to the standard output,
or to the device defined by the @kbd{-F} option. @xref{Copy-out mode}.
Usually @code{find} or @code{ls} is used to provide this list to the
standard input. In the following example you can see the possibilities
for archiving the contents of a single directory.
@example
@cartouche
% ls | cpio -ov > directory.cpio
@end cartouche
@end example
The @kbd{-o} option creates the archive, and the @kbd{-v} option prints
the names of the files archived as they are added. Notice that the options
can be put together after a single @samp{-} or can be placed separately
on the command line. The @samp{>} redirects the @code{cpio} output to
the file @file{directory.cpio}.
If you wanted to archive an entire directory tree, the find command can
provide the file list to @code{cpio}:
@example
@cartouche
% find . -print -depth | cpio -ov > tree.cpio
@end cartouche
@end example
This will take all the files in the current directory, the directories
below and place them in the archive @file{tree.cpio}. Again the @kbd{-o}
creates an archive, and the @kbd{-v} option shows you the name of the
files as they are archived. @xref{Copy-out mode}. Using the @samp{.}
in the @code{find} statement will give you more flexibility when doing
restores, as it will save file names with a relative path vice a hard
wired, absolute path. The @kbd{-depth} option forces @code{find} to
print of the entries in a directory before printing the directory itself.
This limits the effects of restrictive directory permissions by printing
the directory entries in a directory before the directory name itself.
Extracting an archive requires a bit more thought because @code{cpio}
will not create directories by default. Another characteristic is that
it will not overwrite existing files unless you tell it to.
@example
@cartouche
% cpio -iv < directory.cpio
@end cartouche
@end example
This will retrieve the files archived in the file @file{directory.cpio}
and place them in the present directory. The @kbd{-i} option extracts
the archive and the @kbd{-v} shows the file names as they are extracted.
If you are dealing with an archived directory tree, you need to use the
@kbd{-d} option to create directories as necessary, something like:
@example
@cartouche
% cpio -idv < tree.cpio
@end cartouche
@end example
This will take the contents of the archive @file{tree.cpio} and extract
it to the current directory. If you try to extract the files on top of
files of the same name that already exist (and have the same or later
modification time) @code{cpio} will not extract the file unless told to
do so by the @kbd{-u} option. @xref{Copy-in mode}.
In copy-pass mode, @code{cpio} copies files from one directory tree to
another, combining the copy-out and copy-in steps without actually using
an archive. It reads the list of files to copy from the standard input;
the directory into which it will copy them is given as a non-option argument.
@xref{Copy-pass mode}.
@example
@cartouche
% find . -depth -print0 | cpio --null -pvd new-dir
@end cartouche
@end example
The example shows copying the files of the present directory, and
sub-directories to a new directory called new-dir. Some new options are the
@kbd{-print0} available with GNU @code{find}, combined with the @kbd{--null}
option of @code{cpio}. These two options act together to send file names between
find and @code{cpio}, even if special characters are embedded in the file names.
Another is @kbd{-p}, which tells @code{cpio} to pass the files it finds to the
directory @file{new-dir}.
@node tar Tutorial, cpio invocation, cpio Tutorial, Top
@chapter Tutorial introduction to @code{tar}
This chapter guides you through some basic examples of three @code{tar}
subcommands: @value{create}, @value{list}, and @value{extract}. If
you already know how to use some other version of @code{tar}, then you
may not need to read this chapter. This chapter omits most complicated
details about how @code{tar} works.
@menu
* Assumptions:: Assumptions this tutorial makes
* Simplified invokation:: The structure of a @code{tar} command
* Basic tar options:: @code{tar} subcommands and options
* create list extract tutorial:: The three most frequently used subcommands
* file verbose help:: Three frequently used options
* create tutorial:: How to create archives
* list tutorial:: How to list archives
* extract tutorial:: How to extract members from an archive
* Looking ahead:: Looking ahead: The rest of this manual
@end menu
@node Assumptions, Simplified invokation, tar Tutorial, tar Tutorial
@section Assumptions this tutorial makes
This chapter is paced to allow beginners to learn about @code{tar}
slowly. At the same time, we will try to cover all the basic aspects of
these three subcommands. 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:
@itemize @bullet
@item
Before you start to work through this tutorial, you should understand
what the terms ``archive'' and ``archive member'' mean
(@pxref{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
filesystem. 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, the
differences between relative and absolute path names, and the file
permission system.
@item
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 @code{tar} commands in. When we show path names, we will
assume that those paths are relative to your home directory. All of my
examples are in a subdirectory of the directory named by that path name;
the subdirectory is called @file{practice}.
@item
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. @xref{Media}, for complete information on using
@code{tar} archives with tape drives.
@end itemize
@node Simplified invokation, Basic tar options, Assumptions, tar Tutorial
@section The structure of a @code{tar} command
A @code{tar} command has this basic structure:
@smallexample
$ tar @var{subcommand} @var{option} @var{option} @dots{} @var{file} @var{file} @dots{}
@end smallexample
We will explain the various component parts of this command in the
rest of this chapter. For more detailed information about the
structure of a @code{tar} command and how to invoke
@code{tar}, please see @ref{tar invocation}.
@node Basic tar options, create list extract tutorial, Simplified invokation, tar Tutorial
@section @code{tar} subcommands and options
@code{tar} can take a variety of arguments which specify and define
the actions it will have perform on a particular set of files or
an archive. The arguments to @code{tar} fall into one of two classes:
options and non-options. Options start with one or two dashes (@kbd{-}),
except for the very first argument following @kbd{tar} on the command line:
this argument always provides options, even if it does not start with a dash.
Some options fall into a class called @dfn{subcommands}; exactly one of
these is both allowed and required for any instance of using @code{tar};
you may @emph{not} specify more than one. People sometimes speak of them
as @dfn{operating modes}. You are in a particular operating mode when you
have specified the subcommand which calls for that mode; there are eight
subcommands in total, and thus there are eight operating modes.
The other arguments fall into the class known as @dfn{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 @code{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 @code{tar} subcommands and options in any of
three forms: long (mnemonic) form, short form, and old style. Some of
the subcommands and options have no short or ``old'' forms; however, the
subcommands and options which we will cover in this tutorial have
corresponding abbreviations. @FIXME{Make sure this is still the case,
at the end.} We will indicate those abbreviations appropriately to get
you used to seeing them. (Note that the ``old style'' option forms
exist in @code{tar} for compatibility with Unix @code{tar}. We
present a full discussion of this way of writing options and subcommands
in @ref{Old style}, and we discuss the other two styles of
writing options in @ref{Long options} and @ref{Short options}.)
In the examples and in the text of this tutorial, we usually use the
long forms of subcommands and options; but the ``short'' forms produce
the same result and can make typing long @code{tar} commands easier.
For example, instead of typing
@smallexample
$ @kbd{tar --create --verbose --file=afiles.tar apple angst aspic}
@end smallexample
@noindent
you can type
@smallexample
$ @kbd{tar -c -v -f afiles.tar apple angst aspic}
@end smallexample
@noindent
or even
@smallexample
$ @kbd{tar -cvf afiles.tar apple angst aspic}
@end smallexample
@noindent
For more information on option syntax, see @ref{Styles}. 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 ``subcommands''
are often lumped in with the actual, @emph{optional} ``options'' in
certain general class statements. For example, we just talked about
``short and long forms of options and subcommands''. However,
experienced @code{tar} users often refer to these by shorthand terms
such as ``short and long forms of options''. This term assumes that
the ``subcommands'' are included as well. 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 @code{tar} ``commands''.
The term, @code{tar} @dfn{commands}, refers to the various
@emph{subcommands}. However, you will also sometimes hear the term
``the @code{tar} command''. When the word ``command'' is used
specifically like this, a person is usually referring to the whole line,
not the @code{tar} @emph{subcommand}. Again, use context to figure out
which of the meanings the speaker intends.
@FIXME{We thought we knew about tar, but after reading the last two
paragraphs, we are now totally confused. Options are actually subcommands,
subcommands are sometimes commands and sometimes command lines...HEEEELP!!!
We might just throw this away.}
@node create list extract tutorial, file verbose help, Basic tar options, tar Tutorial
@section The three most frequently used subcommands
Here are the three most frequently used subcommands (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 subcommands in detail. We will
present the rest of the subcommands in the next chapter.
@table @asis
@item @value{create}
Create a new @code{tar} archive.
@item @value{list}
List the contents of an archive.
@item @value{extract}
Extract one or more members from an archive.
@end table
@node file verbose help, create tutorial, create list extract tutorial, tar Tutorial
@section Three frequently used options
To understand how to run @code{tar} in the three operating modes listed
previously, you also need to understand how to use two of the options to
@code{tar}: @value{file} (which takes an archive file as an argument)
and @value{verbose}. (You are usually not @emph{required} to specify
either of these options when you run @code{tar}, but they can be very
useful in making things more clear and helping you avoid errors.) A third
option, @value{help}, gives a brief list of subcommands and options.
Unlike other @code{tar} options, @value{help} is not run under any
operating mode; in this sense, it is more like a subcommand, except that
it does not act on any @code{tar} archive.
@menu
* file tutorial:: The @kbd{--file} option
* verbose tutorial:: The @kbd{--verbose} option
* help tutorial:: Getting help: Using the @kbd{--help} option
@end menu
@node file tutorial, verbose tutorial, file verbose help, file verbose help
@subsection The @kbd{--file} option
The @value{file} option specifies the name of an archive file.
You can specify an argument for the @value{file} option whenever you
use @code{tar}; this option determines the name of the archive file that
@code{tar} will work on.
If you don't specify this argument, then @code{tar} will use a default,
usually standard output or standard input, or some physical tape drive
attached to your machine. If there is no tape drive attached, or the
default is not meaningful, then @code{tar} will print an error message.
The error message might look roughly like one of the following:
@smallexample
tar: can't open /dev/rmt8 : No such device or address
tar: can't open /dev/rsmt0 : I/O error
@end smallexample
@noindent
Thus, to avoid this sort of confusion, we recommend that you always
specify an archive file name by using @value{file} when writing your
@code{tar} commands. For more information on using the @value{file}
option, see @ref{file}.
@node verbose tutorial, help tutorial, file tutorial, file verbose help
@subsection The @kbd{--verbose} option
The @value{verbose} option shows the files being worked on as @code{tar}
is running.
@value{verbose} shows details about the results of running
@code{tar}. This can be especially useful when the results might not be
obvious. For example, if you want to see the progress of @code{tar} as
it writes files into the archive, you can use the @value{verbose}
option. In the beginning, you may find it useful to use
@value{verbose} at all times; when you are more accustomed to
@code{tar}, you will likely want to use it at certain times but not at
others. We will use @value{verbose} at times to help make something
clear, and we will give many examples both using and not using
@value{verbose} to show the differences.
Sometimes, a single instance of @value{verbose} on the command line
will show a full, @code{ls}-style listing of an archive or files,
giving sizes, owners, and similar information. Other times,
@value{verbose} will only show files or members that the particular
subcommand is operating on at the time. In the latter case, you can
use @value{verbose} twice in a command to get a listing such as that
in the former case. For example, instead of saying
@smallexample
$ @kbd{tar -cvf afiles.tar apple angst aspic}
@end smallexample
@noindent
above, you might say
@smallexample
$ @kbd{tar -cvvf afiles.tar apple angst aspic}
@end smallexample
@noindent
This works equally well using short or long forms of options. Using long
forms, you would simply write out the option twice, like this:
@smallexample
$ @kbd{tar --create --verbose --verbose @dots{}}
@end smallexample
@noindent
Note that you must double the hyphens properly each time.
Later in the tutorial, we will give examples using @w{@kbd{--verbose
--verbose}}.
@node help tutorial, , verbose tutorial, file verbose help
@subsection Getting help: Using the @kbd{--help} option
The @value{help} option to @code{tar} prints out a summary list of all
options available for the current version of @code{tar} on your system.
There is no abbreviation for this option.
@node create tutorial, list tutorial, file verbose help, tar Tutorial
@section How to create archives
One of the basic subcommands of @code{tar} is @value{create}, which
you use to create a @code{tar} archive. We will explain
@value{create} first because, in order to learn about the other
subcommands, you will find it useful to have an archive available to
practice on.
To make this as easy as possible, you will first create a directory
containing three files (eventually you will create more practice files).
Then, we will show you how to create an @emph{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
@file{blues}, @file{folk}, and @file{jazz}. The archive is called
@file{genres.tar}.
This section will proceed slowly, detailing how to use @value{create}
in @code{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
slowly so that novice users can begin to understand how @code{tar}
works.
@menu
* prepare for examples:: Preparing a practice directory for examples
* Creating the archive tutorial:: Creating the archive
* create verbose:: Running @kbd{--create} with @kbd{--verbose}
* Short create:: Short forms with @kbd{--create}
* create dir tutorial:: Archiving directories
@end menu
@node prepare for examples, Creating the archive tutorial, create tutorial, create tutorial
@subsection Preparing a practice directory for examples
To follow along with this and future examples, create a new directory
called @file{practice} containing files called @file{blues}, @file{folk}
and @file{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 @file{practice}
is a subdirectory of your home directory.
Now @code{cd} to the directory named @file{practice}; @file{practice}
is now your @dfn{working directory}. (@emph{Please note}: Although
the full path name of this directory is
@w{@file{/@var{homedir}/practice}}, in our examples we will refer to
this directory as @file{practice}; the @var{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 @code{ls}. So let's
do it:
@smallexample
$ @kbd{ls}
blues folk jazz
@end smallexample
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, @file{collection.tar}), or that you don't care about its contents.
Whenever you use @kbd{create}, @code{tar} will erase the current contents
of the file named by @value{file} if it exists. @code{tar} will not
tell you if you are about to overwrite a file unless you specify an option
which does this @xref{backup}. To add files to an existing archive, you
need to use a different option, such as @value{append}; see @ref{append}
for information on how to do this.
@FIXME{We don't think there is an option to prevent overwriting an
existing file with an archive when --create is used.}
@node Creating the archive tutorial, create verbose, prepare for examples, create tutorial
@subsection Creating the archive
To place the files @file{blues}, @file{folk}, and @file{jazz} into an
archive named @file{collection.tar}, use the following command:
@smallexample
$ @kbd{tar --create --file=collection.tar blues folk jazz}
@end smallexample
The order of the arguments is not very important, @emph{when using long
option forms}. You could also say:
@smallexample
$ @kbd{tar blues --create folk --file=collection.tar jazz}
@end smallexample
@noindent
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
@code{tar}, to avoid errors).
Note that the part of the command that says
@w{@kbd{--file=collection.tar}} is considered to be @emph{one} argument.
If you substituted any other string of characters for
@kbd{`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.
@xref{Short create}, for more information on this.
In this example, you type the command as shown above: @value{create}
is the subcommand which creates the new archive
(@file{collection.tar}), and @value{file} is the option which lets
you give it the name you chose. The files @file{blues}, @file{folk},
and @file{jazz} are now members of the archive @file{collection.tar}
(they are @dfn{file name arguments} to the @value{create} subcommand).
@FIXME{xref here to the discussion of file name args?} Now that they
are are in the archive, they are called @emph{archive members}, not
files @FIXME{xref to definitions?}.
When you create an archive, you @emph{must} specify which files you want
placed in the archive. If you do not specify any archive members,
@code{tar} will complain.
If you now list the contents of the working directory (@kbd{ls}), you will
find the archive file listed as well as the files you saw previously:
@smallexample
$ @kbd{ls}
blues collection.tar folk jazz
@end smallexample
@noindent
Creating the archive @file{collection.tar} did not destroy the copies of
the files in the directory.
Keep in mind that if you don't indicate any subcommand, @code{tar} will not
run and will prompt you for one. If you don't name any files, @code{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.
@emph{Caution}: Do not attempt to use @value{create} to add files to
an existing archive; it will delete the archive and write a new one.
Use @value{append} instead. @xref{append}.
@node create verbose, Short create, Creating the archive tutorial, create tutorial
@subsection Running @kbd{--create} with @kbd{--verbose}
If you include the @value{verbose} option on the command line,
@code{tar} will list the files it is acting on as it is working. In
verbose mode, the @code{create} example above would appear as:
@smallexample
$ @kbd{tar --create --verbose --file=collection.tar blues folk jazz}
blues
folk
jazz
@end smallexample
This example is just like the example we showed which did not use
@value{verbose}, except that @code{tar} generated the remaining
@iftex
lines (note the different font styles).
@end iftex
@ifinfo
lines.
@end ifinfo
In the rest of the examples in this chapter, we will frequently use
@code{verbose} mode so we can show actions or @code{tar} responses that
you would otherwise not see, and which are important for you to
understand what @code{tar} does.
@node Short create, create dir tutorial, create verbose, create tutorial
@subsection Short forms with @kbd{--create}
As we said before, the @value{create} subcommand is one of the most
basic uses of @code{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 @ref{Styles}; for now, here is what the
previous example (including the @value{verbose} option) looks like
using short option forms:
@smallexample
$ @kbd{tar -cvf collection.tar blues folk jazz}
blues
folk
jazz
@end smallexample
@noindent
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:
@smallexample
$ @kbd{tar -cfv collection.tar blues folk jazz}
tar: Cannot add file collection.tar: No such file or directory
tar: Error exit delayed from previous errors
$ @kbd{ls}
blues folk jazz v
$
@end smallexample
@noindent
You got error messages and a file called @file{v}. What happened is
that @code{tar} tried to make an archive file called @file{v},
containing the files @file{blues}, @file{folk}, and @file{jazz}, because
the @samp{v} is the closest ``file name'' to the @kbd{-f} option, and
is thus taken to be the chosen archive file name. @code{tar} tried
to add a file called @file{collection.tar} to the @file{v} archive file;
if the file @file{collection.tar} did not already exist, @code{tar} will
report an error indicating that this file does not exist. If the file
@file{collection.tar} does already exist (e.g., from a previous command
you may have run), then @code{tar} will add this file to the archive.
Because the @kbd{-v} option did not get registered, @code{tar} will not
run under @emph{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,
@smallexample
$ @kbd{tar blues --create folk --file=collection.tar jazz}
@end smallexample
@noindent
is confusing as it is. When shown using short forms, however, it
becomes much more so:
@smallexample
$ @kbd{tar blues -c folk -f collection.tar jazz}
@end smallexample
@noindent
It would be very easy to put the wrong string of characters
immediately following the @kbd{-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. (Placing options in
an unusual order can also cause @code{tar} to report an error if you have
set the shell environment variable, @code{POSIXLY_CORRECT}; @pxref{posix},
for more information on this.)
@node create dir tutorial, , Short create, create tutorial
@subsection Archiving directories
@cindex Archiving directories
@cindex Directories, Archiving
You can archive a directory by specifying its directory name as a
file name argument to @code{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:
@smallexample
$ @kbd{cd ..}
$
@end smallexample
@noindent
This will put you into the directory which contains @file{practice},
that is, your home directory. Once in the superior directory, you can
specify the subdirectory, @file{practice}, as a file name argument. To
store @file{practice} in the new archive file @file{music.tar}, type:
@smallexample
$ @kbd{tar --create --verbose --file=music.tar practice}
@end smallexample
@noindent
@code{tar} should output:
@smallexample
practice/
practice/blues
practice/folk
practice/jazz
practice/collection.tar
@end smallexample
Note that the archive thus created is not in the subdirectory
@file{practice}, but rather in the current working directory---the
directory from which @code{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 @code{tar}. For example, you will probably
not be able to store your home directory in an archive by invoking
@code{tar} from the root directory; @xref{absolute-names}. (Note
also that @file{collection.tar}, the original archive file, has itself
been archived. @code{tar} will accept any file as a file to be
archived, regardless of its content. When @file{music.tar} is
extracted, the archive file @file{collection.tar} will be rewritten
into the file system).
If you give @code{tar} a command such as
@smallexample
$ @kbd{tar --create --file=foo.tar .}
@end smallexample
@noindent
@code{tar} will report @samp{tar: foo.tar is the archive; not dumped}.
This happens because @code{tar} creates the archive @file{foo.tar}
in the current directory before putting any files into it. Then, when
@code{tar} attempts to add all the files in the directory @file{.} to
the archive, it notices that the file @file{foo.tar} is the same as the
archive, and skips it. (It makes no sense to put an archive into itself.)
@code{tar} will continue in this case, and create the archive normally,
except for the exclusion of that one file. (@emph{Please note:} Some other
versions of @code{tar} are not so clever; they might enter an infinite
loop when this happens. It is safer, in general, not to depend on
@code{tar} behavior, by making sure that the archive is not created
inside a directory that is itself being dumped.) Some MS-Windows file systems
(notably, Windows 95 VFAT disks) don't support the feature which is
used by @code{tar} to detect that the archive is included in itself,
so the archive @emph{will} be included on those file systems.
@node list tutorial, extract tutorial, create tutorial, tar Tutorial
@section How to list archives
Often, you will find yourself wanting to determine exactly what a
particular archive contains. You can use the @value{list} subcommand
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 @file{genres.tar} that you created
in the last section with the command,
@smallexample
$ @kbd{tar --list --file=genres.tar}
@end smallexample
@noindent
The output of @code{tar} would then be:
@smallexample
blues
folk
jazz
@end smallexample
If you use the @value{verbose} option with @value{list}, then
@code{tar} will print out a listing reminiscent of @w{@kbd{ls -l}},
showing owner, file size, and so forth.
If you had used @code{verbose} mode, the example above would look
like:
@smallexample
$ @kbd{tar --list --verbose --file=genres.tar folk}
-rw-rw-rw- myself users 62 1990-05-23 10:55 folk
@end smallexample
@cindex File name arguments, using @value{list} with
@cindex --list with file name arguments
You can specify one or more individual member names as arguments when
using @kbd{list}. In this case, @code{tar} will only list the
names of members you identify. For example, @w{@kbd{tar --list
--file=afiles.tar apple}} would only print @file{apple}.
@menu
* absolute tutorial:: Specifying Member Names Correctly
* Listing directories:: Listing the contents of a stored directory
@end menu
@node absolute tutorial, Listing directories, list tutorial, list tutorial
@subsection Specifying member names correctly
@FIXME{if this stays here, needs an intro paragraph}
@FIXME{need to show the creation of bfiles somewhere above!!! : }
@noindent
The archive @file{bfiles.tar} would list as follows:
@smallexample
./birds
baboon
./box
@end smallexample
@noindent
Be sure to use a @value{file} option just as with @value{create}
to specify the name of the archive.
Because @code{tar} preserves paths, file names must be specified as they
appear in the archive (that is, relative to the directory from which the
archive was created). Therefore, it is essential when specifying member
names to @code{tar} that you give the exact member names. For example,
@w{@kbd{tar --list --file=bfiles birds}} would produce an error message
something like @samp{tar: birds: Not found in archive}, because there is
no member named @file{birds}, only one named @file{./birds}. While the
names @file{birds} and @file{./birds} name the same file, @emph{member}
names are compared using a simplistic name comparison, in which an exact
match is necessary. @xref{absolute-names}.
However, @w{@kbd{tar --list --file=genres.tar folk}} would respond
with @file{folk}, because @file{folk} is in the archive file
@file{genres.tar}. If you are not sure of the exact file name, try
listing all the files in the archive and searching for the one you
expect to find; remember that if you use @value{list} with no file
names as arguments, @code{tar} will print the names of all the members
stored in the specified archive.
@node Listing directories, , absolute tutorial, list tutorial
@subsection 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
@value{list}. To determine file attributes, include the
@value{verbose} option.
For example, to find out about files in the directory @file{practice} in
the archive file @file{music.tar}, type:
@smallexample
$ @kbd{tar --list --verbose --file=music.tar practice}
@end smallexample
@code{tar} responds:
@smallexample
drwxrwxrwx myself users 0 1990-05-31 21:49 practice/
-rw-rw-rw- myself users 42 1990-05-21 13:29 practice/blues
-rw-rw-rw- myself users 62 1990-05-23 10:55 practice/folk
-rw-rw-rw- myself users 40 1990-05-21 13:30 practice/jazz
-rw-rw-rw- myself users 10240 1990-05-31 21:49 practice/collection.tar
@end smallexample
When you use a directory name as a file name argument, @code{tar} acts on
all the files (including subdirectories) in that directory.
@node extract tutorial, Looking ahead, list tutorial, tar Tutorial
@section How to extract members from an archive
@cindex Extraction
@cindex Retrieving files from an archive
@cindex Resurrecting files from an archive
The act of retrieving members from an archive so they can be used and
manipulated as unarchived files again is called @dfn{extraction}. To
extract files from an archive, use the @value{extract} subcommand.
As with @value{create}, specify the name of the archive with
@value{file}. Extracting an archive does not modify the archive in
any way; you can extract it multiple times if you want or need to.
Using @value{extract}, you can extract an entire archive, or specific
files. The files can be directories containing other files, or not. As
with @value{create} and @value{list}, you may use the short or the
long form of the subcommand without affecting the performance.
If you have files in the working directory with the same name as members
that you are about to extract, the files will be overwritten by the newly
extracted members. @code{tar} has new options which will permit you
to keep more than one copy of a file with the same name as an archive is
extracted; for more information about this, consult @ref{backup}.
@menu
* Extracting archives:: Extracting an entire archive
* Extracting files:: Extracting specific files
* Extracting directories:: Extracting files that are directories
* Failing commands:: Commands that will fail
* Two mistakes:: Two dangerous mistakes
@end menu
@node Extracting archives, Extracting files, extract tutorial, extract tutorial
@subsection Extracting an entire archive
To extract an entire archive, specify the archive file name only, with
no individual file names as arguments. For example,
@smallexample
$ @kbd{tar -xvf collection.tar}
@end smallexample
@noindent
produces this:
@smallexample
-rw-rw-rw- myself users 28 1996-10-18 16:31 jazz
-rw-rw-rw- myself users 21 1996-09-23 16:44 blues
-rw-rw-rw- myself users 20 1996-09-23 16:44 folk
@end smallexample
@node Extracting files, Extracting directories, Extracting archives, extract tutorial
@subsection Extracting specific files
To extract specific archive members, give their exact member names as
arguments, as printed by @value{list}. If you have mistakenly deleted
one of the files you had placed in the archive @file{genres.tar} earlier
(say, @file{blues}), you can extract it from the archive without changing the
archive's structure. It will be identical to the original file @file{blues}
that you deleted. @FIXME{will the times, permissions, owner, etc be the
same, also?}
First, make sure you are in the @file{practice} directory, and list the
files in the directory. Now, delete the file @file{blues} and list
the files in the directory again.
You can now extract the member @file{blues} from the archive file
@file{genres.tar} like this:
@smallexample
$ @kbd{tar --extract --file=genres.tar blues}
@end smallexample
@noindent
If you list the files in the directory again, you will see that the file
@file{blues} has been restored, with its original permissions, creation
time, and owner. 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 @emph{not} have been made to the archive member. (If the restoring
user was not also the owner of the archived members, and if the current
@code{umask} is compatible with original permissions, the various
permissions would probably be different.) The archive file
@file{genres.tar} is the same as it was before you extracted
@file{blues}. You can confirm this by running @code{tar} with
@value{list}.
Remember that as with other subcommands, specifying the exact member name
is important. @w{@kbd{tar --extract --file=bfiles.tar birds}} will fail,
because there is no member named @file{birds}. To extract the member named
@file{./birds}, you must specify @w{@kbd{tar --extract --file=bfiles.tar
./birds}}. To find the exact member names of the members of an archive,
use @value{list} (@pxref{list}).
If you give the @value{verbose} option, then @value{extract} will
print the names of the archive members as it extracts them.
@node Extracting directories, Failing commands, Extracting files, extract tutorial
@subsection 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 overwrite
the files already in the pre-existing directory (and possible subdirectories).
This will happen regardless of whether or not the files in the pre-existing
directory were more recent than those extracted.
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, @code{tar} will create the directory.
We can demonstrate how to use @value{extract} to extract a directory
file with an example. Change to the @file{practice} directory if you
weren't there, and remove the files @file{folk} and @file{jazz}. Then,
go back to the parent directory and extract the archive
@file{music.tar}. You may either extract the entire archive, or only
the files you just deleted. To extract the entire archive, don't give
any file names as arguments after the archive name @file{music.tar}. To
extract only the files you deleted, use the following command:
@smallexample
$ @kbd{tar -xvf music.tar practice/folk practice/jazz}
@end smallexample
@FIXME{Need to show tar's response; used verbose above. Also, here's a
good place to demonstrate the -v -v thing.}
@noindent
Because you created the directory with @file{practice} as part of the
file names of each of the files by archiving the @file{practice}
directory as @file{practice}, you must give @file{practice} as part
of the file names when you extract those files from the archive.
@node Failing commands, Two mistakes, Extracting directories, extract tutorial
@subsection 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:
@smallexample
$ @kbd{tar -xvf music.tar folk jazz}
@end smallexample
@noindent
you will get the following response:
@smallexample
tar: folk: Not found in archive
tar: jazz: Not found in archive
$
@end smallexample
@noindent
This is because these files were not originally @emph{in} the parent
directory @file{..} where the archive is located; they were in the
@file{practice} directory, and their file names reflect this:
@smallexample
$ @kbd{tar -tvf music.tar}
practice/folk
practice/jazz
practice/rock
@end smallexample
@noindent
Likewise, if you try to use this command,
@smallexample
$ @kbd{tar -tvf music.tar folk jazz}
@end smallexample
@noindent
you would get a similar response. Members with those names are not in the
archive. You must use the correct member names in order to extract the
files from the archive.
If you have forgotten the correct names of the files in the archive,
use @w{@kbd{tar --list --verbose}} to list them correctly.
@node Two mistakes, , Failing commands, extract tutorial
@subsection Two dangerous mistakes
Here are two dangerous mistakes you should try to avoid which can occur
while using @value{extract}:
@enumerate
@item
@cindex Mistake: use @code{create} instead of @code{extract}
Do not mistakenly use @code{create} instead of @code{extract},
when your intent is to extract the contents of an archive.
This error can occur if you mistype the @kbd{c} key for the @kbd{x} key.
You might do this when you are tired, since the two keys, @kbd{c} and
@kbd{x}, are next to each other on a @sc{QWERTY} keyboard. If you make
this mistake, instead of unpacking the archive, you will destroy it.
@item
@cindex Mistake: forget archive name
Do not mistakenly forget to list the name of the file into which
you are archiving, especially when your intent is to create an
archive with just one file in it.
You might do this by force of habit, by inadvertently adding the @kbd{f}
key to your cluster of option letters while forgetting to name the
archive. If you make this mistake, instead of archiving the file, you
will destroy it.
@end enumerate
@node Looking ahead, , extract tutorial, tar Tutorial
@section Looking ahead: The rest of this manual
You have now seen how to use the main subcommands available to @code{tar},
and a number of the possible options. You should be able to take
advantage of the @code{tar} program adequately to help yourself in many real situations.
The next two chapters review everything you have learned so far, while going
in depth about every topic, most probably to a greater extent than you really
need for simple day-to-day use. The remaining chapters explain how
to choose and change file and archive names, and how to use files to store
names of other files which you can then call as arguments to @code{tar}
(this can help you save time if you expect to archive the same list of
files a number of times).
If there are too many files to list conveniently on the command line,
you can list the names in a file, and @code{tar} will read that file.
@xref{files-from}.
There are various ways of causing @code{tar} to skip over certain files
and not archive them. @xref{Choosing}.
@node cpio invocation, pax invocation, tar Tutorial, Top
@chapter Invoking @code{cpio}
@cindex invoking cpio
@cindex command line options
@menu
* Copy-out mode:: Copy-out mode
* Copy-in mode:: Copy-in mode
* Copy-pass mode:: Copy-pass mode
* cpio Options:: Options for @code{cpio}
@end menu
@node Copy-out mode, Copy-in mode, cpio invocation, cpio invocation
@section Copy-out mode
In copy-out mode, @code{cpio} copies files into an archive. It reads a
list of filenames, one per line, on the standard input, and writes the
archive onto the standard output. A typical way to generate the list
of filenames is with the @code{find} command; you should give find the
@kbd{-depth} option to minimize problems with permissions on directories
that are unreadable. @xref{cpio Options}.
@example
cpio @{-o|--create@} [-0acvABLV] [-C bytes] [-H format]
[-M message] [-O [[user@@]host:]archive] [-F [[user@@]host:]archive]
[--file=[[user@@]host:]archive] [--format=format]
[--message=message][--null] [--reset-access-time] [--verbose]
[--dot] [--append] [--block-size=blocks] [--dereference]
[--io-size=bytes] [--help] [--version] < name-list [> archive]
@end example
@node Copy-in mode, Copy-pass mode, Copy-out mode, cpio invocation
@section Copy-in mode
In copy-in mode, @code{cpio} copies files out of an archive or lists
the archive contents. It reads the archive from the standard input.
Any non-option command line arguments are shell globbing patterns; only
files in the archive whose names match one or more of those patterns are
copied from the archive. Unlike in the shell, an initial @samp{.} in a
filename does match a wildcard at the start of a pattern, and a @samp{/}
in a filename can match wildcards. If no patterns are given, all files
are extracted. @xref{cpio Options}.
@example
cpio @{-i|--extract@} [-bcdfmnrtsuvBSV] [-C bytes] [-E file]
[-H format] [-M message] [-R [user][:.][group]]
[-I [[user@@]host:]archive] [-F [[user@@]host:]archive]
[--file=[[user@@]host:]archive] [--make-directories]
[--nonmatching] [--preserve-modification-time]
[--numeric-uid-gid] [--rename] [--list] [--swap-bytes] [--swap]
[--dot] [--unconditional] [--verbose] [--block-size=blocks]
[--swap-halfwords] [--io-size=bytes] [--pattern-file=file]
[--format=format] [--owner=[user][:.][group]] [--sparse]
[--no-preserve-owner] [--message=message] [--help] [--version]
[--no-absolute-filenames] [--only-verify-crc] [--quiet] [--silent]
[pattern...] [< archive]
@end example
@node Copy-pass mode, cpio Options, Copy-in mode, cpio invocation
@section Copy-pass mode
In copy-pass mode, @code{cpio} copies files from one directory tree to
another, combining the copy-out and copy-in steps without actually creating
an archive. It reads the list of files to copy from the standard input;
the directory into which it will copy them is given as a non-option argument.
@xref{cpio Options}.
@example
cpio @{-p|--pass-through@} [-0adlmuvLV] [-R [user][:.][group]]
[--null] [--reset-access-time] [--make-directories] [--link]
[--preserve-modification-time] [--unconditional] [--verbose]
[--dot] [--dereference] [--owner=[user][:.][group]] [--sparse]
[--no-preserve-owner] [--help] [--version] destination-directory
< name-list
@end example
@node cpio Options, , Copy-pass mode, cpio invocation
@section Options for @code{cpio}
@table @kbd
@item --null
@itemx -0
Read a list of filenames terminated by a @kbd{@key{NUL}} character, instead
of a newline, so that files whose names contain newlines can be archived.
GNU @code{find} is one way to produce a list of null-terminated filenames.
This option may be used in copy-out and copy-pass modes.
@item --reset-access-time
@itemx -a
Reset the access times of files after reading them, so that it does not look
like they have just been read. (This option has no effect on plain DOS,
since DOS filesystem only stores a single time stamp per file. It does
work on Windows 9X.)
@item --append
@itemx -A
Append to an existing archive. Only works in copy-out mode. The archive
must be a disk file specified with the @kbd{-O} or @kbd{-F} (@kbd{--file})
option.
@item --swap
@itemx -b
Swap both halfwords of words and bytes of halfwords in the data. Equivalent
to @kbd{-sS}. This option may be used in copy-in mode. Use this option
to convert 32-bit integers between big-endian and little-endian machines.
@item -B
Set the I/O block size to 5120 bytes. Initially the block size is 512 bytes.
@item --block-size=@var{block-size}
Set the I/O block size to @var{block-size} * 512 bytes.
@item -c
Use the old portable (ASCII) archive format.
@item --io-size=@var{io-size}
@itemx -C @var{io-size}
Set the I/O block size to @var{io-size} bytes.
@item --make-directories
@itemx -d
Create leading directories where needed.
@item --pattern-file=@var{file}
@itemx -E @var{file}
Read additional patterns specifying filenames to extract or list from
@var{file}. The lines of @var{file} are treated as if they had been
non-option arguments to @code{cpio}. This option is used in copy-in mode.
@item --nonmatching
@itemx -f
Only copy files that do not match any of the given patterns.
@item --file=@var{archive}
@itemx -F @var{archive}
Archive filename to use instead of standard input or output. To use a
tape drive on another machine as the archive, use a filename that starts
with @samp{@var{HOSTNAME}:}. The hostname can be preceded by a username
and an @samp{@@} to access the remote tape drive as that user, if you have
permission to do so (typically an entry in that user's @file{~/.rhosts}
file).
Remote archives are not supported on MS-DOS and MS-Windows.
@item --force-local
With @kbd{-F}, @kbd{-I}, or @kbd{-O}, take the archive file name to be a
local file even if it contains a colon, which would ordinarily indicate
a remote host name.
@item --format=@var{format}
@item -H @var{format}
Use archive format @var{format}. The valid formats are listed below;
the same names are also recognized in all-caps. The default in copy-in
mode is to automatically detect the archive format, and in copy-out mode
is @code{bin}.
@table @code
@item bin
The obsolete binary format.
@item odc
The old (POSIX.1) portable format.
@item newc
The new (SVR4) portable format, which supports file systems having more
than 65536 i-nodes.
@item crc
The new (SVR4) portable format with a checksum added.
@item tar
The old @code{tar} format.
@item ustar
The POSIX.1 @code{tar} format. Also recognizes most @code{tar} archives,
many of which are similar, but not identical.
@item hpbin
The obsolete binary format used by HPUX's @code{cpio} (which stores device
files differently).
@item hpodc
The portable format used by HPUX's @code{cpio} (which stores device files
differently).
@end table
@item --extract
@itemx -i
Run in copy-in mode. @xref{Copy-in mode}.
@item -I @var{archive}
Archive filename to use instead of standard input. To use a tape drive
on another machine as the archive, use a filename that starts with
@samp{@var{hostname}:}. The hostname can be preceded by a username and
an @samp{@@} to access the remote tape drive as that user, if you have
permission to do so (typically an entry in that user's @file{~/.rhosts}
file).
Remote archives are not supported on MS-DOS and MS-Windows.
@item -k
Ignored; for compatibility with other versions of @code{cpio}.
@item --link
@itemx -l
Link files instead of copying them, when possible.
@item --dereference
@itemx -L
Copy the file that a symbolic link points to, rather than the symbolic
link itself.
@item --preserve-modification-time
@itemx -m
Retain previous file modification times when creating files.
@item --message=@var{message}
@itemx -M @var{message}
Print @var{message} when the end of a volume of the backup media (such
as a tape or a floppy disk) is reached, to prompt the user to insert a
new volume. If @var{message} contains the string @samp{%d}, it is replaced
by the current volume number (starting at 1).
@item --numeric-uid-gid
@itemx -n
Show numeric UID and GID instead of translating them into names when using
the @kbd{--verbose option}.
@item --no-absolute-filenames
Create all files relative to the current directory in copy-in mode, even
if they have an absolute file name in the archive.
@item --no-preserve-owner
Do not change the ownership of the files; leave them owned by the user
extracting them. This is the default for non-root users, so that users
on System V don't inadvertantly give away files. This option can be used
in copy-in mode and copy-pass mode
@item --create
@itemx -o
Run in copy-out mode. @xref{Copy-out mode}.
@item -O @var{archive}
Archive filename to use instead of standard output. To use a tape
drive on another machine as the archive, use a filename that starts with
@samp{@var{hostname}:}. The hostname can be preceded by a username and
an @samp{@@} to access the remote tape drive as that user, if you have
permission to do so (typically an entry in that user's @file{~/.rhosts}
file).
Remote archives are not supported on MS-DOS and MS-Windows.
@item --only-verify-crc
Verify the CRC's of each file in the archive, when reading a CRC format
archive. Don't actually extract the files.
@item --pass-through
@itemx -p
Run in copy-pass mode. @xref{Copy-pass mode}.
@item --quiet
@itemx --silent
Do not print the number of blocks copied.
@item --rename
@itemx -r
Interactively rename files. For each file in the archive, @code{cpio} will
print its name and wait for the user to type a new name. An empty name
(produced by pressing @kbd{RET}) means skip the file.
@item --rename-batch-file=@var{rename-file}
Non-interactively rename files. For each file in the archive, @code{cpio}
will read a replacement name from the named @var{rename-file}. In that
file, file names should be separated by newlines. An empty line causes
@code{cpio} to skip the file.
@item --owner [@var{user}][:.][@var{group}]
@itemx -R [@var{user}][:.][@var{group}]
Set the ownership of all files created to the specified user and/or group
in copy-in and copy-pass modes. Either the user, the group, or both,
must be present. If the group is omitted but the @samp{:} or @samp{.}
separator is given, use the given user's login group. Only the super-user
can change files' ownership.
(On MS-DOS and MS-Windows, any user can use this option, since changing
ownership is a no-op on these systems.)
@item --swap-bytes
@itemx -s
Swap the bytes of each halfword (pair of bytes) in the files. This option
can be used in copy-in mode.
@item --swap-halfwords
@itemx -S
Swap the halfwords of each word (4 bytes) in the files. This option may
be used in copy-in mode.
@item --sparse
Write files with large blocks of zeros as sparse files. This option is
used in copy-in and copy-pass modes.
@item --list
@itemx -t
Print a table of contents of the input.
@item --unconditional
@itemx -u
Replace all files, without asking whether to replace existing newer files
with older files.
@item --verbose
@itemx -v
List the files processed, or with @kbd{-t}, give an @samp{ls -l} style table
of contents listing. In a verbose table of contents of a ustar archive,
user and group names in the archive that do not exist on the local system
are replaced by the names that correspond locally to the numeric UID and
GID stored in the archive.
@item --dot
@itemx -V
Print a @kbd{.} for each file processed.
@item --version
Print the @code{cpio} program version number and exit.
@end table
@node pax invocation, tar invocation, cpio invocation, Top
@chapter Invoking @code{pax}
This chapter is not written yet.
@node tar invocation, Subcommands, pax invocation, Top
@chapter Invoking @code{tar}
This chapter is about how one invokes the @code{tar} command, from the
command synopsis (@pxref{Synopsis}). There are numerous options, and many
styles for writing them. One option should specify the subcommand @code{tar}
should perform (@pxref{Subcommand summary}); other options are meant to
detail how this subcommand should be performed (@pxref{Option summary}).
Non-option arguments are not always interpreted the same way; their
interpretation depends on what the subcommand is.
You will find in this chapter everything about option styles and rules
for writing them (@pxref{Styles}). On the other hand, most subcommands
and options are described elsewhere, in other chapters. Here, you will
find only synthetic descriptions for subcommands and options, together
with pointers to other parts of the @code{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 @code{tar} or
else they globally alter the amount of feedback the user receives about
what is going on. This chapter describes the @value{help} (@pxref{help})
option, as well as @value{version} (@pxref{version}), @value{verbose}
(@pxref{verbose}), @value{interactive} (@pxref{interactive}), and a
few others.
@menu
* Synopsis:: General synopsis of @code{tar}
* Using options:: Using @code{tar} options
* Styles:: The three option styles
* Documentation and help:: Documentation and troubleshooting
* interactive:: Asking for confirmation during subcommands
@end menu
@node Synopsis, Using options, tar invocation, tar invocation
@section General synopsis of @code{tar}
The @code{tar} program is invoked as either one of:
@smallexample
$ @kbd{tar} @var{option}@dots{} [@var{name}]@dots{}
$ @kbd{tar} @var{letter}@dots{} [@var{argument}]@dots{} [@var{option}]@dots{} [@var{name}]@dots{}
@end smallexample
The second form is for when old options are being used.
You can use @code{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 @code{tar}, which is called the @dfn{subcommand}, specifies
which action to take. The other arguments to @code{tar} are either
@dfn{options}, which change the way @code{tar} performs a subcommand,
or file names or archive members, which specify the files or members
@code{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. The option stating the operation mode (the @code{tar}
subcommand) is usually given first.
Each @var{name} in the synopsis above is interpreted as an archive member
name when the subcommand is one of @value{compare}, @value{delete},
@value{extract}, @value{list} or @value{update}. When naming
archive members, you must give the exact name of the member in the
archive, as it is printed by @value{list}. For @value{append}
and @value{create}, these @var{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 @code{tar} command.
@code{tar} interprets relative file names as relative to the
working directory. @code{tar} will make all file names relative
(by removing leading slashes when archiving or restoring files)
unless you specify otherwise (using the @value{absolute-names}
option). @xref{absolute-names}, for more information about
@value{absolute-names}.
If you give the name of a directory as either a file name or a member
name, then @code{tar} acts recursively on all the files and directories
beneath that directory. For example, the name @file{/} identifies all
the files in the filesystem to @code{tar}.
The distinction between file names and archive member names is especially
important when shell globbing is used, and is sometimes a source of confusion
for newcomers. @xref{Wildcards}, for more information about globbing.
The problem is that shells can only glob using existing files in the
file system. Only @code{tar} itself can glob on archive members, so when
that is necessary, you must ensure that wildcard characters reach @code{tar} without
being interpreted by the shell first. Using a backslash before @samp{*}
or @samp{?}, or putting the whole argument between quotes, is usually
sufficient for this. (On MS-DOS/MS-Windows, you @strong{must} use
quotes, since the backslash is a directory separator, and cannot be used
to escape-protect wildcard characters.)
Even if @var{name}s are often specified on the command line, they
can also be read from a text file in the file system, using the
@value{files-from} option.
If you don't use any file name arguments, @value{append},
@value{delete} and @value{concatenate} will do nothing, while
@value{create} will usually yield a diagnostic and inhibit @code{tar}
execution. The other subcommands of @code{tar} (@value{list},
@value{extract}, @value{compare}, and @value{update}) will act
on the entire contents of the archive.
@cindex exit status
@cindex return status
Besides successful exits, @code{tar} may fail for many reasons. Some reasons
correspond to bad usage, that is, when the @code{tar} command is improperly
written. Errors may also be encountered later, while processing the archive
or the files. Some errors are recoverable, in which case the failure is
delayed until @code{tar} has completed all its work, @code{tar} then says:
@example
tar: Processed all files possible, despite earlier errors
@end example
@noindent
just before exiting with a nonzero status.@footnote{The message used to be
``Error exit delayed from previous errors'', but many users complained
they did not understand what this means, so we changed the message.}
When @code{tar} is executed interactively and reports a recoverable error,
the supplementary time before the prompt reappears, the noise coming from
the disk, or the sight of the actual tape moving, gives some feel to the
user that @code{tar} continued its processing. But when run in scripts
or unattended, the ending message is undoubtly useful.
Some errors are such that it would not be meaningful, or at least would be
risky, to continue processing: @code{tar} then aborts processing immediately,
and says so. All abnormal exits, whether immediate or delayed, should
@emph{always} be clearly diagnosed on @code{stderr}, after a line stating
the nature of the error. When an error is recoverable, @code{tar} attempts
to continue processing as much as possible. It will then exit with an
error (nonzero) status, which is in fact delayed from the time the error
effectively occurred.
@code{tar} returns only a few exit statuses. We are really aiming for
simplicity in that area, for now.@footnote{@code{tar} once had a complex
system of exit codes, which became unreliable over time, forcing a great
cleanup in version 1.11.8.} If you are not using the @value{compare} option,
zero means that everything went well, besides maybe innocuous warnings
(however, @pxref{ignore-failed-read}). Nonzero means that something
went wrong. As of today, ``nonzero'' is almost always 1 or 2, except for
remote subcommands, where it may be 128. The value 1 is meant to report a
difference (@pxref{compare}), while the value 2 represents all other errors.
The @code{tar} program is often used early in a pipe, in which case the
exit status of @code{tar} is less easy to obtain, as the error exit of
the whole pipe is the error exit of the last program in the pipeline. If you
are using @code{bash}, check the @code{PIPESTATUS} array for @code{tar}'s
exit status. Otherwise, it @emph{is} possible with @code{sh} or @code{ksh}
to fetch the exit status of a process in the middle of a pipeline, just
ugly:@footnote{This clever recipe has been communicated by Brendan O'Dea.}
@smallexample
$ @kbd{exec 3>&1}
$ @kbd{status=`((tar @dots{}; echo $? >&4) | tee @dots{} >&3) 4>&1`}
@end smallexample
@node Using options, Styles, Synopsis, tar invocation
@section Using @code{tar} options
@code{tar} has about 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 @code{tar} program, by specifying one and only one
subcommand as an argument to the @code{tar} command (@pxref{Subcommands}).
Depending on the 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 @code{tar}'s performance by running @code{tar}
with one or more options (such as @value{verbose}). @dfn{options} are
arguments to @code{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 how @code{tar} works on archives, 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 @pxref{All options}.)
Note that @code{tar} options are case sensitive. For example, the
options @kbd{-T} and @kbd{-t} are different; the first requires an
argument for stating the name of a file providing a list of @var{name}s,
while the second does not require an argument and is another way to
write @value{list}.
In addition to the eight subcommands, there are many options to
@code{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 subcommands can be written in any of these three
styles.
@node Styles, Documentation and help, Using options, tar invocation
@section The three option styles
There are three styles for writing subcommands and options to the command
line invoking @code{tar}. The different styles were developed at different
times during the history of @code{tar}. These styles will be presented
below, from the most recent to the oldest.
Some options must take an argument. (For example, @value{file} takes the
name of an archive file as an argument. If you do not supply an archive
file name, @code{tar} will use a default which may vary from site to
site; thus, we recommend that you always supply a specific archive file
name in your portable scripts.) Where you @emph{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 make(s) the most sense to you until you
feel comfortable with the others.
@menu
* Long options:: Long option style
* Short options:: Short option style
* Old style:: Old option style
* Mixing:: Mixing option styles
@end menu
@node Long options, Short options, Styles, Styles
@subsection Long option style
Each option has at least one long (or mnemonic) name starting with two
dashes in a row, for example, @value{list}. The long names are clearer than
their short or old equivalents. It sometimes happens that a
single long option has many different names which are synonymous, such
as @w{@kbd{--compare}} and @w{@kbd{--diff}}. In addition, long option
names can be given unique abbreviations. For example, @w{@kbd{--cre}} can
be used in place of @value{create} because there is no other long option
which begins with @samp{cre}. (One way to find this out is by trying it
and seeing what happens;@footnote{Be aware that if you run @code{tar} with
a unique abbreviation for the long name of an option you didn't want to
use, you are stuck; @code{tar} will perform the command as ordered.} if
a particular abbreviation could represent more than one option, @code{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 @w{@kbd{tar --help}}
to see a list of options.)
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,
@smallexample
$ @kbd{tar --create --verbose --blocking-factor=20 --file=/dev/rmt0}
@end smallexample
@noindent
gives a fairly good set of hints about what the command does, even
for those not fully acquainted with @code{tar}.
Long options which require arguments take those arguments immediately
following the option name; they are introduced by an equal sign. For
example, the @value{file} option (which tells the name of the @code{tar}
archive) is given a file such as @file{archive.tar} as argument by using
the notation @w{@kbd{--file=archive.tar}} for the long option.
@node Short options, Old style, Long options, Styles
@subsection 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, for example, @kbd{-t} (which
is equivalent to @w{@kbd{--list}}). The forms are absolutely identical in
function; they are interchangeable. Short option names are often preferred
as they 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 @w{@kbd{-f archive.tar}}
or @kbd{-farchive.tar} instead of using @w{@kbd{--file=archive.tar}}. Both
@w{@kbd{--file=@var{archive-name}}} and @w{@kbd{-f @var{archive-name}}} denote
the option which indicates a specific archive, here named @file{archive.tar}.
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.
@w{@kbd{tar -cvf}}. Only the last option in such a set is allowed
to have an argument.@footnote{Clustering many options, the last of which
has an argument, is a rather opaque way to write options. Some wonder if
GNU @code{getopt} should not even be made helpful enough to reject
such usages as invalid.}
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:
@smallexample
$ @kbd{tar -c -v -b 20 -f /dev/rmt0}
@end smallexample
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.
@node Old style, Mixing, Short options, Styles
@subsection Old option style
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.@footnote{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.} This set
of letters must be the first to appear on the command line, after the
@code{tar} program name and some whitespace; 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 @kbd{t}
is the same as the short option @kbd{-t}, and consequently, the same as the
long option @value{list}. So for example, the command @w{@kbd{tar cv}}
specifies the option @kbd{-v} in addition to the subcommand @kbd{-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:
@smallexample
$ @kbd{tar cvbf 20 /dev/rmt0}
@end smallexample
@noindent
Here, @samp{20} is the argument of @kbd{-b} and @samp{/dev/rmt0} is
the argument of @kbd{-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 @w{@kbd{tar cvbf 20 /dev/rmt0}}, for example,
@samp{20} is the argument for @kbd{-b}, @samp{/dev/rmt0} is the
argument for @kbd{-f}, and @kbd{-v} does not have a corresponding
argument. Even using short options, as in @w{@kbd{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 @code{tar} options can surprise even experienced
users. For example, the two commands:
@smallexample
$ @kbd{tar cfz archive.tar.gz file}
$ @kbd{tar -cfz archive.tar.gz file}
@end smallexample
@noindent
are quite different! The first example uses @file{archive.tar.gz} as
the value for option @kbd{f} and recognizes the option @kbd{z}. The
second example, however, uses @file{z} as the value for option
@kbd{f}---probably not what the user intended.
This example could be corrected in many ways, among which the
following are equivalent:
@smallexample
$ @kbd{tar -czf archive.tar.gz file}
$ @kbd{tar -cf archive.tar.gz -z file}
$ @kbd{tar cf archive.tar.gz -z file}
@end smallexample
@cindex option syntax, traditional
As far as we know, all @code{tar} programs support old options.
This @code{tar} supports them not only for historical reasons, but also
because many people are used to them. Old options have their own
virtues, like inter-operability in portable scripts, and concise writing.
@node Mixing, , Old style, Styles
@subsection Mixing option styles
All three styles may be intermixed in a single @code{tar} command, so
long as the rules for each style are fully respected.@footnote{Before
@code{tar} version 1.11.6, a bug prevented intermixing old-style options
with long options in some cases.} old-style options and either of the
modern styles of options may be mixed within a single @code{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 @code{tar} command and some whitespace). 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.
@smallexample
$ @kbd{tar --create --file=archive.tar}
$ @kbd{tar --create -f archive.tar}
$ @kbd{tar --create -farchive.tar}
$ @kbd{tar --file=archive.tar --create}
$ @kbd{tar --file=archive.tar -c}
$ @kbd{tar -c --file=archive.tar}
$ @kbd{tar -c -f archive.tar}
$ @kbd{tar -c -farchive.tar}
$ @kbd{tar -cf archive.tar}
$ @kbd{tar -cfarchive.tar}
$ @kbd{tar -f archive.tar --create}
$ @kbd{tar -f archive.tar -c}
$ @kbd{tar -farchive.tar --create}
$ @kbd{tar -farchive.tar -c}
$ @kbd{tar c --file=archive.tar}
$ @kbd{tar c -f archive.tar}
$ @kbd{tar c -farchive.tar}
$ @kbd{tar cf archive.tar}
$ @kbd{tar f archive.tar --create}
$ @kbd{tar f archive.tar -c}
$ @kbd{tar fc archive.tar}
@end smallexample
On the other hand, the following commands are @emph{not} equivalent to
the previous set:
@smallexample
$ @kbd{tar -f -c archive.tar}
$ @kbd{tar -fc archive.tar}
$ @kbd{tar -fcarchive.tar}
$ @kbd{tar -farchive.tarc}
$ @kbd{tar cfarchive.tar}
@end smallexample
@noindent
These last examples mean something completely different from what the
user intended (judging by the example in the previous set which uses long
options, whose intent is therefore very clear). The first four specify
that the @code{tar} archive would be a file named @file{-c}, @file{c},
@file{carchive.tar} or @file{archive.tarc}, respectively. The first two
examples also specify a single non-option, @var{name} argument having the
value @samp{archive.tar}. The last example contains only old-style option
letters (repeating option @kbd{c} twice), not all of which are meaningful
(for example, @kbd{.}, @kbd{h}, or @kbd{i}), with no argument value.
@node Documentation and help, interactive, Styles, tar invocation
@section Documentation and troubleshooting
@cindex Progress information
@cindex Status information
@cindex Information on progress and status of subcommands
@cindex Verbose subcommand
@cindex Block number where error occured
@cindex Error message, block number of
@cindex Version of the @code{tar} program
@cindex Getting more information
@cindex Information during operation
@cindex Feedback from @code{tar}
@menu
* version:: Knowing the @code{tar} version
* help:: Getting the list of possible options
* verbose:: Checking @code{tar} progress
* checkpoint:: Being warned of all directories
* show-omitted-dirs:: Being warned of skipped directories
* totals:: Sizeing the amount of data written
* block-number:: Adding physical addresses to messages
@end menu
@node version, help, Documentation and help, Documentation and help
@subsection Knowing the @code{tar} version
To be careful, the first thing is to check that you are really using the
proper @code{tar}. The @value{version} option will generate a
message giving confirmation that you are using this @code{tar}, with the
precise version you are using. @code{tar} identifies itself and prints the
version number to the standard output, then immediately exits successfully,
without doing anything else, ignoring all other options. For example,
@w{@kbd{tar --version}} might return:
@smallexample
tar (Free paxutils) @value{VERSION}
@end smallexample
@noindent
The first occurrence of @samp{tar} in the result above is the program
name in the package (for example, @code{rmt} is another program), while
the second occurrence of @samp{tar} is the name of the package itself,
containing possibly many programs. The package is currently named
@samp{tar}, after the name of the main program it contains.@footnote{There
are plans to merge the @code{cpio} and @code{tar} packages into a single one
which would be called @code{paxutils}. So, who knows if, one of this days,
the @value{version} would not yield @w{@samp{tar (Free paxutils) 3.2}}.}
@node help, verbose, version, Documentation and help
@subsection Getting the list of possible options
You might also want to check the spelling or meaning
of some particular @code{tar} option, without resorting to this manual,
once you have read it. @code{tar} has a short help
feature, triggerable through the @value{help} option. By using this
option, @code{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 though 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:
@smallexample
$ @kbd{tar --help | less}
@end smallexample
@noindent
presuming, here, that you like using @code{less} for a pager. Other
popular pagers are @code{more} and @code{pg}. If you know about some
@var{keyword} which interests you and do not want to read all the
@value{help} output, another common idiom is:
@smallexample
$ @kbd{tar --help | grep @var{keyword}}
@end smallexample
@noindent
to get only the pertinent lines.
The perceptive reader would have noticed some contradiction in the
previous paragraphs. It is written that both @value{version} and
@value{help} print something, and have all other options ignored. In
fact, they cannot ignore each other, and one of them has to win. We do
not specify which is stronger; experiment if you really wonder!
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 @code{tar} manual in some form. This manual
is available in printed form, as a kind of small book. It may be printed out
of the @code{tar} distribution, provided you have @TeX{} already installed
somewhere, and a laser printer around. Just configure the distribution,
execute the command @w{@kbd{make dvi}}, then print @file{doc/tar.dvi} the
usual way (contact your local @emph{guru} to know how). If @code{tar} has
been conveniently installed at your site, this manual is also available
in interactive, hypertextual form as an Info file. Just call @w{@kbd{info
tar}} or, if you do not have the @code{info} program handy, use the Info
reader provided within GNU Emacs, and choose @kbd{tar} from the main Info
menu (with @kbd{m tar @key{RET}}).
A short reference to @code{tar} in the form of a @code{man} page is also
provided. Currently, it doesn't tell much more than @kbd{tar --help} does.
Other @code{man} pages exist for @code{tar}, written at the time @code{tar}
did not install any @code{man} pages on its own. The string @samp{tar
(Free paxutils) @value{VERSION}} appears in the title of the @emph{normal}
@code{man} page.
@node verbose, checkpoint, help, Documentation and help
@subsection Checking @code{tar} progress
Typically, @code{tar} performs most subcommands without reporting any
information to the user except error messages. When using @code{tar} with
many options, particularly ones with complicated or difficult-to-predict
behavior, it is possible to make serious mistakes. @code{tar} provides
several options that make observing its behavior easier. These options cause
@code{tar} to print information as it progresses in its job, and you might
want to use them just to be more careful about what is going on, or
merely to entertain 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 @value{list} command to list an archive prints just
the file names (one per line), and the other commands are silent.
When used with most subcommands, the @value{verbose} option causes
@code{tar} to print the name of each file or archive member as it
is processed. This and the other options which make @code{tar} print
status information can be useful in monitoring @code{tar}.
With @value{create} or @value{extract}, @value{verbose} used once
just prints the names of the files or members as they are processed.
Using it twice causes @code{tar} to print a longer listing (reminiscent
of @kbd{ls -l}) for each member. Since @value{list} already prints
the names of the members, @value{verbose} used once with @value{list}
causes @code{tar} to print an @kbd{ls -l} type listing of the files
in the archive. The following examples both extract members with
long list output:
@smallexample
$ @kbd{tar --extract --file=archive.tar --verbose --verbose}
$ @kbd{tar xvv archive.tar}
@end smallexample
Verbose output appears on the standard output except when an archive is
being written to the standard output, as with @kbd{tar --create --file=-
--verbose} (@kbd{tar cfv -}, or even @kbd{tar cv}---if the installer let
standard output be the default archive). In that case @code{tar} writes
verbose output to the standard error stream.
Some people felt the need to produce an archive on standard output,
while still
wishing to segregate verbose output from error output. A possible
approach (on systems allowing it) would be to use a named pipe to receive
the archive, and to have the consumer process read from that named pipe.
This has the advantage of leaving standard output free to receive verbose
output, all separate from errors.
@node checkpoint, show-omitted-dirs, verbose, Documentation and help
@subsection Being warned of all directories
The @value{checkpoint} option prints an occasional message as @code{tar}
reads or writes the archive. In fact, it print directory names while
reading the archive. It is designed for those who don't need the more
detailed (and voluminous) output of @value{block-number}, but do want
visual confirmation that @code{tar} is actually making progress.
@node show-omitted-dirs, totals, checkpoint, Documentation and help
@subsection Being warned of skipped directories
The @value{show-omitted-dirs} option, when reading an archive---with
@value{list} or @value{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),
or it might be excluded by the use of the @value{exclude} option, or
for some other reason.
@node totals, block-number, show-omitted-dirs, Documentation and help
@subsection Sizeing the amount of data written
The @value{totals} option---which is only meaningful when used with
@value{create}---causes @code{tar} to print the total amount written to
the archive, after it has been fully created.
Currently, the amount written represents the size of the created archive
before it gets compressed. One wants to estimate the size of the used portion of a tape
receiving a compressed archive, and as it stands, the option is not as useful
as it should be. Some later version of @code{tar} will change the meaning
of this option to print the total amount written once compression has occurred.
@node block-number, , totals, Documentation and help
@subsection Adding physical addresses to messages
If @value{block-number} is used, @code{tar} prints, along with every
message it would normally produce, the block number within the archive
where the message was triggered (@xref{Blocking}, to understand blocks
and records). Also, supplementary messages are triggered when reading
blocks full of @code{NUL}s, or when hitting end of file on the archive.
As of now, if the archive is properly terminated with a @code{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 @value{block-number} is used.
Note that @code{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
@value{list} when listing a filesystem 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). @FIXME{xref when the node name is set and the
backup section written.}
Some later version of @code{tar} might use @w{@kbd{--number-blocks}}
instead of @w{@kbd{--block-number}}, so @w{@kbd{--block}} would then expand to
@value{blocking-factor} unambiguously.
@node interactive, , Documentation and help, tar invocation
@section Asking for confirmation during subcommands
@cindex Interactive action
@cindex Acting interactively
Typically, @code{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
(@pxref{Choosing}), or by performing a subcommand interactively, using
the @value{interactive} option.
When the @value{interactive} option is specified, before reading, writing,
or deleting files, @code{tar} first prints a message for each such file,
telling what action 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 @kbd{y}. If your input line
begins with anything other than @kbd{y}, @code{tar} skips that file.
If @code{tar} is reading the archive from the standard input, @code{tar}
opens the file @file{/dev/tty} to support the interactive communications.
@node Subcommands, Choosing, tar invocation, Top
@chapter @code{tar} subcommands
A long while ago, @code{tar} once was a set of related programs,
each dedicated to a particular function, like the creation of a new
archive, listing the contents of an archive, or performing extraction.
It was done that way in order to have smaller independent programs,
and better limit the memory requirements of each of them, at a time when
computer memory was expensive. Nowadays, such a split is no longer
necessary, and the single @code{tar} program has a few special options,
named @dfn{subcommands}, meant to set the particular function to be achieved
in a @code{tar} run, just as users once had to choose exactly which
program of the @code{tar} family they needed for a given job.
This chapter has the purpose of presenting such @code{tar} subcommands
or operating modes. It also introduces many options meant to precisely control,
or fine-tune, the behavior of the subcommands. The separation between
subcommands and fine-tuning options is not cast in stone, and should
not be overemphasized. This @code{tar} does implement such
precise distinctions internally, of course, but this does not preclude
future changes or adjustments. In any case, none of these changes, if
they ever occur, should much affect how @code{tar} is used in practice.
Besides @value{help} and @value{version}, which trigger
special behavior in @code{tar}, the most popular subcommands are
@value{list}, @value{extract}, and @value{create}; these are
available in almost all implementations of the @code{tar} program.
The remaining subcommands are @value{compare}, @value{append},
@value{update},@footnote{Currently, @value{update} might be seen as
either a subcommand or a fine-tuning option, depending on how it is used.}
@value{concatenate}, and @value{delete}. These remaining subcommands
are often not offered in various @code{tar}s, and when available, they
seem to be much less often used than the three popular ones.
@menu
* list:: How to list archives
* extract:: How to extract members from an archive
* create:: How to create archives
* Applications:: Other uses for @code{tar}
@end menu
@node list, extract, Subcommands, Subcommands
@section How to list archives
Frequently, you will find yourself wanting to determine exactly what a
particular archive contains. You can use the @value{list} subcommand
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 @file{collection.tar} that you
created in the last section with the command
@smallexample
$ @kbd{tar --list --file=collection.tar}
@end smallexample
@noindent
The output of @code{tar} would then be:
@smallexample
blues
folk
jazz
@end smallexample
@FIXME{We might need to show the creation of bfiles somewhere above! (?)}
@noindent
The archive @file{bfiles.tar} would list as follows:
@smallexample
./birds
baboon
./box
@end smallexample
@noindent
Be sure to use a @value{file} option, just as with @value{create},
to specify the name of the archive.
If you use the @value{verbose} option with @value{list}, then
@code{tar} will print out a listing reminiscent of @w{@kbd{ls -l}},
showing owner, file size, and so forth.
If you had used @value{verbose} mode, the example above would look
like:
@smallexample
$ @kbd{tar --list --verbose --file=collection.tar}
-rw-rw-rw- myself users 42 1990-05-21 13:29 blues
-rw-rw-rw- myself users 62 1990-05-23 10:55 folk
-rw-rw-rw- myself users 40 1990-05-21 13:30 jazz
@end smallexample
@cindex File name arguments, using @value{list} with
@cindex --list with file name arguments
You can specify one or more individual member names as arguments when
using @kbd{list}. In this case, @code{tar} will only list the
names of members you identify. For example, @w{@kbd{tar --list
--file=afiles.tar apple}} would only print @file{apple}.
Because @code{tar} preserves paths, file names must be specified as they
appear in the archive (that is, relative to the directory from which the
archive was created). Therefore, it is essential when specifying member
names to @code{tar} that you give the exact member names. For example,
@w{@kbd{tar --list --file=bfiles birds}} would produce an error message
something like @samp{tar: birds: Not found in archive}, because there is
no member named @file{birds}, only one named @file{./birds}. While the
names @file{birds} and @file{./birds} name the same file, @emph{member}
names are compared using a simplistic name comparison, in which an exact
match is necessary. @xref{absolute-names}.
However, @w{@kbd{tar --list --file=collection.tar folk}} would respond
with @file{folk}, because @file{folk} is in the archive file
@file{collection.tar}. If you are not sure of the exact file name, try
listing all the files in the archive and searching for the one you
expect to find; remember that if you use @value{list} with no file
names as arguments, @code{tar} will print the names of all the members
stored in the specified archive.
As an exception to member name preservation when creating the archive,
@code{tar} on MS-DOS/MS-Windows mirrors the DOS-style backslashes into
Unix-style forward slashes. This is because the bulk of @code{tar} code
is deeply entrenched in the Unix world and assumes that forward slashes
are used in too many places. Converting slashes automatically lets the
users specify files as they are used to on those systems. But it also
means that you need to remember about this conversion, so you won't be
surprised when @code{tar} lists the files differently than what you
typed on the command line. For example:
@smallexample
$ @kbd{tar -cvf c:\files\backup\today.tar d:\data\may97 d:\data\june97}
data/may97
data/june97
$ @kbd{tar -xvf c:\files\backup\today.tar data\may97}
data/may97
@end smallexample
@cindex ISO 8601 Dates
@cindex 8601 Dates (ISO)
@cindex Dates format
In the past, @code{tar} showed dates as @samp{Nov 21 1996}; now it shows
them as @samp{1996-11-21}. This is in accordance with the international
standard ISO 8601.@footnote{You can revert to the old behavior by defining
@code{USE_OLD_CTIME} in @file{src/list.c} before reinstalling @code{tar}.}
Sometime in the future, local date formats will become readily
available, including the civilian American month-day-year format.
However, as a general rule, we suggest that you use the ISO 8601 date
format which lists units of time in a larger-to-smaller order.
For more information, see
@uref{http://www.ft.uni-erlangen.de/~mskuhn/iso-time.html}, which
contains a detailed explanation of the ISO 8601 standard.
@menu
* Reading:: Options to help read archives
* compare:: Comparing members with the file system
@end menu
@node Reading, compare, list, list
@subsection Options to help read archives
@cindex Options when reading archives
@cindex Reading incomplete records
@cindex Records, incomplete
@cindex End-of-archive entries, ignoring
@cindex Ignoring end-of-archive entries
@cindex Large lists of file names on small machines
@cindex Small memory
@cindex Running out of space
If you're not sure of the blocking factor of an archive, you can read the
archive by specifying @value{read-full-records} and @value{blocking-factor},
using a blocking factor larger than what the archive uses. This lets
you avoid having to determine the blocking factor of an archive.
@xref{blocking-factor}.
@menu
* read-full-records:: Reading full records
* ignore-zeros:: Ignoring blocks of zeros
* ignore-failed-read:: Ignoring read failures
@end menu
@node read-full-records, ignore-zeros, Reading, Reading
@subsubsection Reading full records
The @value{read-full-records} option is used in conjunction with
@value{extract} to read an archive which contains incomplete records,
or one which has a blocking factor less than the one specified.
If @value{read-full-records} is used, @code{tar} will not panic if an
attempt to read a record from the archive does not return a full record.
Instead, @code{tar} will keep reading until it has obtained a full
record.
This option is turned on by default when @code{tar} is reading
an archive from standard input, or from a remote machine. This is
because on BSD Unix systems, a read of a pipe will return however
much happens to be in the pipe, even if it is less than @code{tar}
requested. If this option was not used, @code{tar} would fail as
soon as it read an incomplete record from the pipe.
This option is also useful with the commands for updating an archive.
Normally, @code{tar} will request data in full record increments from
an archive storage device. If the device cannot return a full record,
@code{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 @value{read-full-records} option in conjunction with
the @value{extract} or @value{list} subcommands. @xref{read-full-records}.
The @value{read-full-records} option is turned on by default when @code{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, @code{tar} would fail as soon as it read
an incomplete record from the pipe.
@node ignore-zeros, ignore-failed-read, read-full-records, Reading
@subsubsection Ignoring blocks of zeros
Normally, @code{tar} stops reading when it encounters a block of zeros
between file entries (which usually indicates the end of the archive).
POSIX mandates two blocks of zeros for representing the end of the archive.
Some @code{tar} programs produce two such blocks on write and expect two on
read, others produce one and expect one. This @code{tar} produces two and
expects one, but is careful, while reading a pipe, to fully drain it until
the end of file. This avoids spurious messages about @cite{broken pipes}.
Yet there are many @code{tar} programs around and many ways to produce
compressed archives, and also many ways to read them. It happens that
when @code{gunzip} and @code{tar} collaborate to explode an archive,
@code{gunzip} quits while @code{tar} still expects a full-sized record,
with proper padding after the end of archive block. This surely caused
a few headaches to users observing the breaking of the pipe within their
@code{sh} scripts, and yet unable to reproduce the problem interactively,
one line at a time, within their @code{csh} shell. Contrarily to @code{sh},
@code{csh} remains silent about broken pipes!
The @value{ignore-zeros} option causes @code{tar} to ignore blocks of
zeros in the archive and to read until the real end of the archive file.
@value{ignore-zeros} allows @code{tar} to completely read an archive
which contains a block of zeros before the end (for example,@: a damaged archive,
or one which was created by @code{cat}-ing several archives together).
The @value{ignore-zeros} option is turned off by default because many
versions of @code{tar} write garbage after the end-of-archive entry, since
that part of the media is normally not supposed to be read. The garbage
is likely to be duplicate copies of the previous chunk of the archive,
which will sometimes cause files to be overwritten or truncated since it
may look like valid new archived files.
@node ignore-failed-read, , ignore-zeros, Reading
@subsubsection Ignoring read failures
When the @value{ignore-failed-read} option is given, @code{tar} will
not exit with an error (nonzero) status, for the sole reason of having
encountered unreadable files or directories.
When backing up a living file system, there is a time window between the
phase when @code{tar} scans directories and the phase when it tries to
open files to dump them. It is possible, and even common, for the file to
disappear during this window. The @value{ignore-failed-read} option is a
way to ask @code{tar} not to report such problems as an error set in the
exit status once the dump is completed. Diagnostics are still reported,
as the option does not turn them off.
A disappearing file is just a stronger case of the following problem. When a
file shrinks or grows while being backed up, @code{tar} makes some stunts
to ensure the integrity of the archive, so the file length in the header
already written does not lie about what is found in the archive. This might
imply padding the file with zeroes up to the proper length, or writing less
than the actual file contents. In such cases, @code{tar} protected the
integrity of the archive, but surely not the integrity of the file, which
just cannot be restored properly. The @value{ignore-failed-read} more
or less means to not return an error and continue processing even when file
integrity is known to be lost, as long as the archive integrity is preserved.
The @value{--ignore-failed-read} also inhibits an error exit also for
failed opening of directories, files for which dumping type is not known,
or with the @value{remove-files} option, failed removal of files after dump.
@node compare, , Reading, list
@subsection Comparing members with the file system
@cindex Verifying the currency of an archive
The @value{compare} subcommand 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 @emph{only} specify archive member names, not file
names. If you do not name any members, then @code{tar} will compare the
entire archive. If a file is represented in the archive but does not
exist in the file system, @code{tar} reports a difference.
You have to specify the record size of the archive when modifying an
archive with a non-default record size.
@code{tar} ignores files in the file system that do not have
corresponding members in the archive.
The following example compares the archive members @file{rock},
@file{blues}, and @file{funk} in the archive @file{bluesrock.tar} with
files of the same name in the file system. (Note that there is no file
@file{funk}; @code{tar} will report an error message.)
@smallexample
$ @kbd{tar --compare --file=bluesrock.tar rock blues funk}
rock
blues
funk: File does not exist
@end smallexample
@noindent
@FIXME{What does this actually depend on? Let's make a guess, here.
It depends on the type of the file.}
@ignore
Depending on the system where you are running @code{tar} and the
version you are running,
@end ignore
@noindent
If the file in the archive is a link, @code{tar} may have a different
error message, such as
@smallexample
funk: Does not exist
@end smallexample
The intent behind the @value{compare} option is to check whether the
archive represents the current state of files on disk, more than to validate
the integrity of the archive media. For this latter goal, @xref{verify}.
@cindex Timestamp differences, on MS-DOS/MS-Windows filesystems
@cindex Mod time differs message on MS-DOS disks
Some filesystems, such as the FAT and VFAT used on MS-DOS and
MS-Windows, only maintain file modification times up to the nearest even
second. @code{tar} compiled for such systems knows about this, and
doesn't report a difference in mod times unless it is larger than one
second. But if you run @code{tar} on Unix and your files reside on a
FAT disk (via some network interface), you could have some false alarms
in this case.
@node extract, create, list, Subcommands
@section How to extract members from an archive
@cindex Extraction
@cindex Retrieving files from an archive
@cindex Resurrecting files from an archive
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 @dfn{extraction}. To extract files
from an archive, use the @value{extract} subcommand. As with
@value{create}, specify the name of the archive with @value{file}.
Extracting an archive does not modify the archive in any way; you can
extract it multiple times if you want or need to.
Using @value{extract}, you can extract an entire archive, or specific
files. The files can be directories containing other files, or not. As
with @value{create} and @value{list}, you can use the short or the
long form of the subcommand without affecting the performance.
@menu
* extract options:: Options used for extraction
* Writing:: Changing how @code{tar} writes files
* Preventing overwrite:: Options to prevent overwriting files
* Unlinking:: Options to destroy files
* Attributes:: Handling file attributes
* Scarce:: Coping with scarce resources
@end menu
@node extract options, Writing, extract, extract
@subsection Options used for extraction
The previous chapter showed how to use @value{extract} to extract
an archive into the filesystem. Various options cause @code{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 @value{extract} when certain special
considerations arise. You can review the information presented in
@ref{extract} for more basic information about the
@value{extract} subcommand.
Within a @code{tar} archive, a socket is stored as a pipe.
When archives created on Unix are extracted on MS-DOS and MS-Windows
3.x, several problems pop up due to their incompatibilities with the
Unix filesystem. @code{tar} has several tricks up its sleeves to
overcome such problems:
@itemize @bullet{}
@cindex Filenames, illegal characters on MS-DOS
@cindex Extracting files on MS-DOS, illegal characters
@item Illegal characters in file names:
the MS-DOS filesystem disallows certain characters from appearing in a file
name. Except on Windows 9X, it also doesn't allow file names with a
leading dot and file names with more that a single dot in the basename
of the file.
@code{tar} tries to repair such names automatically, by replacing
the offending characters with legal ones. For example, @file{.emacs} is
exracted as @file{_emacs}, @file{foo.bar.c} will be converted to
@file{foo_bar.c}, @file{lost+found} will become @file{lost_found}, and
so forth.
(@code{tar} even tries to be intelligent by treating some cases
specially; for example, files which end with @file{.c++} are extracted
as @file{.cxx}.)
When the file is thus renamed, @code{tar} will print a message to that
effect when operating verbosely (@pxref{verbose}). Note that if a
directory needs to be renamed, @code{tar} will print such a message for
all the files in that directory.
@item DOS device names:
MS-DOS and MS-Windows define their own reserved names for character
devices. For example, the console device is @file{CON}, the printer
device is @file{PRN}, the serial port device is @file{AUX}, and so forth.
These names are special on DOS, in that files with these names, if they
exist in any directory, are inaccessible: the device driver will
intercept any file-related call before the filesystem ever sees it.
(That's because MS-DOS wants to create an illusion that the devices are
present in every directory; in contrast, on Unix the devices live under
a special directory called @file{/dev}.)
When archives created on Unix are unpacked on MS-DOS, they might include
files with these ``forbidden'' names, such as @file{prn.txt} or
@file{aux.c}. Trying to extract such files will lead to crashes, system
wedges, and other atrocities, as the device drivers will try to
interpret the data they get and act on it (for example, some devices are
read-only, and don't know how to handle incoming data).
Therefore, @code{tar} checks every file name it is about to extract, and
if it refers to a character device, @code{tar} changes that file's name
by prepending an underscore @file{_} to it; thus, @file{aux.c} will be
extracted as @file{_aux.c}. (Actually, @code{tar} tries to prepend up
to 2 underscore characters, each time checking if the new name is a
regular file. If both attempts are unsuccessful, @code{tar} will print
an error message and refuse to extract that file.)
As with illegal characters, @code{tar} announces each renamed file when
under verbose operation.
@end itemize
@node Writing, Preventing overwrite, extract options, extract
@subsection Changing how @code{tar} writes files
@cindex Overwriting old files, prevention
@cindex Protecting old files
@cindex Modification times of extracted files
@cindex Permissions of extracted files
@cindex Modes of extracted files
@cindex Writing extracted files to standard output
@cindex Standard output, writing extracted files to
@node Preventing overwrite, Unlinking, Writing, extract
@subsection Options to prevent overwriting files
Normally, @code{tar} writes extracted files into the file system without
regard to the files already on the system; that is, files with the same
names as archive members are overwritten when the archive is extracted.
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 found to be in the way of extraction.
To prevent @code{tar} from extracting an archive member from an archive
if doing so will overwrite a file in the file system, use
@value{keep-old-files} in conjunction with @value{extract}. When
this option is specified, @code{tar} will report an error stating the
name of the file in conflict instead of overwriting the file with the
corresponding extracted archive member.
The @value{unlink-first} option removes existing files, symbolic links,
empty directories, devices, and so forth, @emph{prior} to extracting over them.
This could take care of several situations where overwriting files is
undesirable.
One such situation occurs when the archive includes a regular file whereas
the filesystem has a symbolic link by the same name. Using this option
will prevent @code{tar} from overwriting the file to which the symbolic
link points by the contents of an extracted file, since the link itself
is removed prior to the extraction.
Another situation is with overwriting a running program's executable
file. On some systems, the backing store for the executable @emph{is}
the original program file; overwriting it while the program runs could
lead to segmentation violation and other crashes. You could use the
@value{unlink-first} option to prevent such woes when extracting
arbitrary executables over currently running copies. Note that if
something goes wrong with the extraction and you @emph{did} use this
option, you might end up with no file at all. Without this option, if
something goes wrong with the extraction, the existing file is not
overwritten, and is preserved. (If you want to be safe either way, use
both @value{unlink-first} and @value{backup}; @xref{backup}.)
If you specify the @value{recursive-unlink} option, @code{tar} removes
@emph{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. For example, someone using this feature
may be very surprised at the results when extracting something over a
directory entry from the archive. This option can be dangerous; be very
aware of what you are doing if you choose to use it.
Without @value{recursive-unlink}, @code{tar} silently overwrites
non-directories, but will never overwrite existing non-empty
directories.
@cindex Removing existing files on MS-DOS
@cindex Overwriting prevention on MS-DOS and MS-Windows
One especially nasty subtlety with both @value{unlink-first} and
@value{recursive-unlink} options happens on filesystems which
silently truncate the names of the files in the archive when they are
extracted to the file system. (MS-DOS and MS-Windows 3.X are two
notorious examples.) In such a case, @code{tar} might accidentally delete
a file or a directory which has nothing to do with the extracted file,
simply because their names are the same after truncation. We recommend
that you not use these two options on such filesystems. In fact, we recommend
that if you unpack on MS-DOS archives which were created on Unix, you
@emph{always} use either @value{keep-old-files} or @value{backup},
to prevent the overwriting of existing files due to file name truncation.
@xref{backup}.
@menu
* keep-old-files:: Keeping old files
* to-stdout:: Writing to standard output
* backup:: Backup options
* suffix:: Deciding the backup file suffixes
@end menu
@node keep-old-files, to-stdout, Preventing overwrite, Preventing overwrite
@subsubsection Keeping old files
The @value{keep-old-files} option prevents @code{tar} from overwriting
existing files with archive members having the same name. The
@value{keep-old-files} option is meaningless with @value{list}.
Prevents @code{tar} from overwriting files in the file system during
extraction.
@node to-stdout, backup, keep-old-files, Preventing overwrite
@subsubsection Writing to standard output
To write the extracted files to the standard output, instead of
creating the files on the file system, use @value{to-stdout} in
conjunction with @value{extract}. 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. You might need to use this option to
browse one or more files with a pager such as @code{less}, or if you
want the extracted file to have another name on the file system.
If you extract multiple members, they appear on standard output concatenated,
in the order they are found in the archive.
When this option is used, @code{tar} is careful to not alter the file system.
@code{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 only meaningful with @value{extract}.
@FIXME{Why would you want to do such a thing, how are files separated on
the standard output? is this useful with more that one file? Are
pipes the real reason?}
@node backup, suffix, to-stdout, Preventing overwrite
@subsubsection Backup options
@cindex backup options
@cindex backups, making
@code{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 to individual extracted members. Other free programs (GNU @code{cp},
@code{install}, @code{ln}, and @code{mv}, for example) offer similar options.
Backup options may prove unexpectedly useful when extracting archives
containing many members having identical names, or when extracting archives
on systems having file name limitations, making different members appear
as having similar names through the side-effect of name truncation.
(This is true only if we have a good scheme for truncated backup names,
of which we are not sure at all: we suspect work is needed in this area.
The MS-DOS/MS-Windows version works with numbered backups even when file
names are truncated.) When any existing file is backed up before being
overwritten by extraction, clashing files are automatically 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.
We recommend that you @strong{always} use numbered backups when unpacking
archives on MS-DOS and on other systems that have file name limitations.
When @code{tar} is given the @value{backup} option, it makes backups of
files that are about to be overwritten or removed. Without this option,
the original versions are destroyed. However, @xref{keep-old-files}.
At the detail level, some decisions are still experimental, and may
change in the future. We are awaiting comments from our users. So please
do not get in the habit of depending 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.
Some people express the desire to @emph{always} use the @value{backup}
option by defining some kind of alias or script. This is not as easy
as one may think, due to the fact that old-style options should appear first
and consume arguments a bit unpredictably for an alias or script. But
if you are ready to give up using old-style options, you may resort to
using something like a (Bourne shell) function here:
@smallexample
$ @kbd{tar () @{ /usr/local/bin/tar --backup $*; @}}
@end smallexample
@vindex VERSION_CONTROL
@cindex backup files, type made
The @value{backup} option also accepts an optional value,
@var{method}, which determines the type of backups that will be made. If this value is
not given, the value of the @code{VERSION_CONTROL} environment variable
is used. And if @code{VERSION_CONTROL} is not set, the default backup
method is @kbd{existing}.
@vindex version-control @r{Emacs variable}
This value corresponds to the Emacs variable @samp{version-control}; the
same values for @var{method} are accepted as in Emacs. The values also
have more descriptive names. Here are the valid @var{method}s (unique
abbreviations are accepted):
@table @kbd
@item t
@itemx numbered
@opindex numbered @r{backup method}
Always make numbered backups.
@item nil
@itemx existing
@opindex existing @r{backup method}
Make numbered backups of files that already have them, simple backups
of the others.
@item never
@itemx simple
@opindex simple @r{backup method}
Always make simple backups.
@end table
@node suffix, , backup, Preventing overwrite
@subsubsection Deciding the backup file suffixes
@cindex backup suffix
@vindex SIMPLE_BACKUP_SUFFIX
@opindex --suffix
The @value{suffix} option informs @code{tar} about the @var{suffix}
which should be appended to each backup file made when @value{backup}
is used. If the @value{suffix} option is not specified, the value
of the @code{SIMPLE_BACKUP_SUFFIX} environment variable is used. And if
@code{SIMPLE_BACKUP_SUFFIX} is not set, the default is @samp{~}, just as
in Emacs.
@node Unlinking, Attributes, Preventing overwrite, extract
@subsection Options to destroy files
Some people argue that @code{tar} should not hesitate to overwrite files
with other files when extracting. When extracting a @code{tar} archive, they
expect to see a faithful copy of the state of the filesystem when the archive
was created. It is debatable that this would always be proper behavior.
For example, suppose one has an archive in which @file{usr/local} is a
link to @file{usr/local2}. Since the archive was created, maybe the site
removed the link and renamed the whole hierarchy from @file{/usr/local2}
to @file{/usr/local}. Such things happen all the time. We guess it would
not be welcome at all, in the typical case, for @code{tar} to remove the
whole hierarchy just to make room for the link to be reinstated, unless it
@emph{also} simultaneously restores the full @file{/usr/local2}, of course!
By default, @code{tar} errs on the side of caution. Some options
allow users to change its behavior. When no special options are
given for this, @code{tar} removes single files when extracting over them,
usually follows symbolic links when found, and does not destroy directories.
@menu
* unlink-first:: Removing files prior to extraction
* recursive-unlink:: Removing whole directories
@end menu
@node unlink-first, recursive-unlink, Unlinking, Unlinking
@subsubsection Removing files prior to extraction
The @value{unlink-first} option tells @code{tar} to try removing files
before extracting over them, instead of trying to overwrite them.
@node recursive-unlink, , unlink-first, Unlinking
@subsubsection Removing whole directories
When the @value{recursive-unlink} option is specified, @code{tar}
tries to remove files and directory hierarchies before extracting over them.
@strong{This is a dangerous option!}
So, @code{tar} is indeed able to remove a whole hierarchy to reestablish a
symbolic link, for example, but @emph{only if} @value{recursive-unlink}
is specified to allow this behavior.
@node Attributes, Scarce, Unlinking, extract
@subsection Handling file attributes
@menu
* touch:: Setting modification times
* same-owner:: Restoring file ownership
* same-permissions:: Setting access permissions
* no-attributes:: Leaving file attributes alone
@end menu
@node touch, same-owner, Attributes, Attributes
@subsubsection Setting modification times
Normally, @code{tar} sets the modification times of extracted files to
the modification times recorded for the files in the archive, but
limits the permissions of extracted files by the current @code{umask}
setting.
To set the modification times of extracted files to the time when
the files were extracted, use the @value{touch} option in
conjunction with @value{extract}.
In fact, @value{touch} sets the 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 @value{extract}.
The @value{touch} option does not extract file modification time.
When this option is used, @code{tar} leaves the modification time
of the files it extracts as the time when the files were extracted,
instead of setting it to the time recorded in the archive.
This option is meaningless with @value{list}.
@node same-owner, same-permissions, touch, Attributes
@subsubsection Restoring file ownership
The @value{same-owner} option invites @code{tar} to create extracted
files with the same ownership they have in the archive, if this is possible.
When using @code{tar} as super-user at extraction time, ownership is always restored.
So this option is meaningful only for non-root users, when @code{tar} is
executed on those systems able to give files away. This is considered as
a security flaw by many people, at least because it makes quite difficult
to correctly charge users for the disk space they occupy. Also, the
@code{suid} or @code{sgid} attributes of files are easily and silently
lost when files are given away.
When writing an archive, @code{tar} writes the user ID and user name
separately. If it can't find a user name (because the user ID is not
in @file{/etc/passwd}), it does not write one. When restoring,
and doing a @code{chmod}, as when you use @value{same-permissions},
(@FIXME{same-owner?}) it tries to look up the name (if one was written)
in @file{/etc/passwd}. If it fails, then it uses the user ID stored in
the archive instead.
@node same-permissions, no-attributes, same-owner, Attributes
@subsubsection Setting access permissions
The @value{same-permissions} option requests the extraction of all
protection information. This option causes @code{tar} to set the modes
(access permissions) of extracted files exactly as recorded in the archive.
If this option is not used, the current @code{umask} setting limits the
permissions on extracted files.
To set the modes (access permissions) of extracted files to those
recorded for those files in the archive, use @value{same-permissions}
in conjunction with the @value{extract} subcommand.
The @value{same-permission} option asks that the modes of
extracted archive members be those recorded in the archive, ignoring
current umask settings. Use in conjunction with @value{extract}.
@FIXME{why doesnt' this cat files together, why is this useful. Is it
really useful with more than one file?}
This option is meaningless with @value{list}.
@node no-attributes, , same-permissions, Attributes
@subsubsection Leaving file attributes alone
The experimental @value{no-attributes} option has the effect of
inhibiting all attempts at restoring file attributes, like owner, group,
mode, or time stamps. In this case, @code{tar} lets the underlying system
handle such things, and does not try to intervene in any way.
@node Scarce, , Attributes, extract
@subsection Coping with scarce resources
@cindex Middle of the archive, starting in the
@cindex Running out of space during extraction
@cindex Disk space, running out of
@cindex Space on the disk, recovering from lack of
@menu
* starting-file:: Starting file
* same-order:: Same order
* preserve:: Preserving permissions and order
@end menu
@node starting-file, same-order, Scarce, Scarce
@subsubsection Starting file
Part of an archive may be skipped through the usage of the
@value{starting-file} option. It forces the chosen subcommand to start
in the middle of an archive. Use in conjunction with @value{extract}
or @value{list}.
If a previous attempt to extract files failed due to lack of disk space,
you can use @value{starting-file} to start extracting only after member
@var{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 @code{tar}, remove unnecessary files
from the file system, and then restart the same @code{tar} subcommand.
In this case, @value{starting-file} is not necessary. @xref{incremental},
@xref{interactive}, and @ref{exclude}.)
@node same-order, preserve, starting-file, Scarce
@subsubsection Same order
The @value{same-order} option allows @code{tar} to process large lists
of file names on machines with small amounts of memory. Use in conjunction
with @value{compare}, @value{list}, or @value{extract}.
The @value{same-order} option tells @code{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 @kbd{tar -t} on the archive and editing its output.
This option is probably never needed on modern computer systems.
@node preserve, , same-order, Scarce
@subsubsection Preserving permissions and order
Bizarrely, the @value{preserve} option is the same as using both
@value{same-permissions} and @value{same-order} simultaneously.
The @value{preserve} option has no equivalent short option name. It is
really equivalent to @value{same-permissions} plus @value{same-order}.
@node create, Applications, extract, Subcommands
@section How to create archives
One of the basic subcommands of @code{tar} is @value{create}, which
you use to create a @code{tar} archive. We will explain
@value{create} first because, in order to learn about the other
subcommands, 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
@emph{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
@file{blues}, @file{folk}, and @file{jazz}. The archive is called
@file{collection.tar}.
This section will proceed slowly, detailing how to use @value{create}
in @code{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
@code{tar} works.
Creating an empty archive would have a kind of elegance. One can
initialize an empty archive and later use @value{append} for adding
all members. Some applications would not welcome making an exception
in the way of adding the first archive member.
@cindex Empty archive, how to create
@cindex Create empty archive
@cindex Archive, create empty
There is little or no reason to create an empty archive, but you can if
you wish. (In itself, an empty archive is useless, but later you can
use @value{append} to add members. There are no actions using an
empty archive that you cannot do as well or better with a regular
archive.) Moreover, there have been reports that some versions of
@code{tar} have trouble with an empty archive on magnetic tapes.
Consequently, @code{tar} will not create an empty archive directly;
specifically, @code{tar} will not create an archive if you specify
the @value{create} option but fail to specify @value{files-from}
and do not provide any arguments besides options.
If, after considering all this, you should want to create an empty
archive, you must specify a value for the @value{files-from} option
that has no names in it, as in the following example:
@smallexample
$ @kbd{tar --create --file=empty-archive.tar --files-from=/dev/null}
$ @kbd{tar cfT empty-archive.tar /dev/null}
@end smallexample
On the other hand, many people reported that it is dangerously easy for
@code{tar} to destroy a magnetic tape with an empty archive.@footnote{This
is well described in @cite{The Unix-Hater's Handbook} by Simson Garfinkel,
Daniel Weise, and Steven Strassmann, IDG Books, ISBN 1-56884-203-1.} The two
most common errors are:
@enumerate
@item
Mistakingly using @code{create} instead of @code{extract}, when the intent
was to extract the full contents of an archive. This error is likely: keys
@kbd{c} and @kbd{x} are right next ot each other on the QWERTY keyboard.
Instead of being unpacked, the archive then gets wholly destroyed.
When users speak about @dfn{exploding} an archive, they usually mean
something else @dots{} Ahem!
@item
Forgetting the argument to @code{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 @kbd{f} key to the cluster of option
letters, by the mere force of habit, without realizing the full
consequences of doing so. The usual consequence is that the single
file, which was meant to be archived, is instead destroyed.
@end enumerate
So, recognizing the likelihood and the catastrophic nature of these
errors, @code{tar} now distances itself from elegance, and
cravenly refuses to create an archive when @value{create} option is
given, there are no arguments besides options, and @value{files-from}
option is @emph{not} used. Observe:
@smallexample
$ @kbd{tar c}
tar: Cravenly refusing to create an empty archive
Try `tar --help' for more information.
$ @kbd{tar cf foo}
tar: Cravenly refusing to create an empty archive
Try `tar --help' for more information.
@end smallexample
@noindent
To get around the cautiousness of
@code{tar} and nevertheless create an archive with nothing in it,
one may still use, as the value for the @value{files-from} option,
a file with no names in it, as shown in the following commands:
@smallexample
$ @kbd{tar --create --file=empty-archive.tar --files-from=/dev/null}
$ @kbd{tar cfT empty-archive.tar /dev/null}
@end smallexample
@menu
* name-prefix:: Using name prefixes
* atime-preserve:: Preserving last access time
* remove-files:: Removing files
* append:: How to add files to existing archives
* update:: Updating an archive
@end menu
@node name-prefix, atime-preserve, create, create
@subsection Using name prefixes
@cindex Name Prefixes,
@cindex Prefixes, Name
Sometimes the directory structure you want an archive to create when you
unpack it is different from the directory structure you built it in.
This is often true when you are using a @code{tar} production in a
makefile, to build distribution archives in a source-code directory.
The most convenient way to do this would be with a command like the
following:
@smallexample
$ @kbd{tar --create --file=distribution.tar *}
@end smallexample
@noindent
But this makes an archive that will unpack as a lot of individual files,
which is usually not what you want. Assuming your build directory is
named `project', you might do something like
@smallexample
$ @kbd{tar --directory=.. --create --file=distribution.tar project}
@end smallexample
But this means you will be stuck with the name of your build directory
as the top-level name of the distribution archive. Often you would like
your distribution archive to unpack into a single directory, but with
a synthetic top-level directory name (perhaps including a version number).
You can get this effect with the @value{name-prefix} option. Its
argument is a name prefix which gets prepended to each file name entry
in an archive as it is added to the archive.
For example, if you say
@smallexample
$ @kbd{tar --name-prefix='project-5.23/' --create --file=collection.tar *}
@end smallexample
you will make an archive of all the files and directories in the
current directory, but it will extract into the single subdirectory
@file{project-5.23}.
Note that you will almost always want the argument of
@value{name-prefix} to end with a directory delimiter (forward slash
under Unix-like operating systems, forward slash or backslash under DOS).
Otherwise you will make an archive in which each file has a prefix
welded directly to the first segment of its name. While this capability
is there for full generality, it is probably not what you want.
@node atime-preserve, remove-files, name-prefix, create
@subsection Preserving last access time
When @code{tar} reads files, their access time gets updated. To have
@code{tar} attempt to set the access times back to what they were before
they were read, use the @value{atime-preserve} option. This doesn't work
for files that you don't own, unless you're root, and it doesn't interact
nicely with incremental dumps (@pxref{Backups}), but it is good enough
for some purposes.
This options also preserves the modification time field, which has no
effect unless the file is being modified simultaneously by another program.
As such, it also can eliminate evidence of reading or writing of the file
by another program, if the access happens between the beginning and ending
of @code{tar} reading the file.
A drawback of the @value{atime-preserve} option is that it alters the
@code{ctime} of the dumped files. Some system administrators value
@code{ctime} much more than @code{atime}.@footnote{This is at least the case
of the current @code{paxutils} maintainer!} They should ponder carefully
the advantages and disadvantages before using this option in system backups.
This option doesn't have any effect on MS-DOS, since @code{atime} is not
supported by the DOS FAT file system. (It @emph{does} work on MS-Windows
9X.)
@node remove-files, append, atime-preserve, create
@subsection Removing files
The effect of the @value{remove-files} option is to remove files once
they have been added to the archive.
@FIXME{What happens if the archive cannot be completed?}
@node append, update, remove-files, create
@subsection How to add files to existing archives
If you want to add files to an existing archive, you don't need to
create a new archive; you can use @value{append}. The archive must
already exist in order to use @value{append}. (A related subcommand
is the @value{update} subcommand; you can use this to add newer
versions of archive members to an existing archive. To learn how to
do this with @value{update}, refer to @ref{update}.)
@FIXME{Explain in second paragraph whether you can get to the previous
version -- explain whole situation somewhat more clearly.}
If you use @value{append} to add a file to an archive which already
contains a member with the same name, then the
old member is not deleted. What does happen, however, is somewhat
complex. @code{tar} @emph{allows} you to have infinite numbers of
archive members
with the same name. Some subcommands treat these same-named members no
differently than any other set of archive members: for example, if you
view an archive with @value{list}, you will see all of those members
listed, with their modification times, owners, etc.
Other subcommands don't deal with these members as well as you might
prefer; if you were to use @value{extract} to extract the archive,
only the most recently added copy of a member with the same name as
other members would end up in the working directory. This is because
@value{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 @emph{overwrite} a file of
the same name which existed in the directory already, and @code{tar}
will not prompt you about this. Thus, only the most recently archived
member will end up being extracted, as it will overwrite the one
extracted before it, and so on. (One way of extracting all of the
members without overwriting them is to use the @value{backup}
option; see @ref{backup}.)
Other than using @value{backup}, there are a few additional ways to
get around this. @FIXME{xref Multiple Members with the Same Name.}
@cindex Members, replacing with other members
@cindex Replacing members with other members
If you want to replace an archive member, use @value{delete} to
delete the member you want to remove from the archive, and then use
@value{append} to add the member you want to be in the archive.
(Replacing one member with another will not work on certain types of
media, such as tapes; see @ref{delete} and @ref{Media}, for more
information.) Note that you cannot 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.
@menu
* Appending files:: Appending files to an archive
* Multiple files:: Multiple files with the same name
@end menu
@node Appending files, Multiple files, append, append
@subsubsection Appending files to an archive
@cindex Adding files to an Archive
@cindex Appending files to an Archive
@cindex Archives, Appending files to
The simplest way to add a file to an already existing archive is the
@value{append} subcommand, which writes specified files into the
archive whether or not they are already among the archived files. When
you use @value{append}, you @emph{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 subcommands, the member names of the newly added
files will be exactly the same as their names given on the command line
(except that backslashes in MS-DOS file names are mirrored to Unix-style
forward slashes). The @value{verbose} option will print out the
names of the files as they are written into the archive.
@value{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 @code{tar} archive, or else the results of using this
subcommand will be unpredictable. @xref{Media}.
To demonstrate use of @value{append} to add a file to an archive,
create a file called @file{rock} in the @file{practice} directory.
Make sure you are in the @file{practice} directory. Then, run the
following @code{tar} command to add @file{rock} to
@file{collection.tar}:
@smallexample
$ @kbd{tar --append --file=collection.tar rock}
@end smallexample
@noindent
If you now use the @value{list} subcommand, you will see that
@file{rock} has been added to the archive:
@ignore
@smallexample
$ @kbd{tar --list --file=collection.tar}
-rw-rw-rw- myself users 28 1996-10-18 16:31 jazz
-rw-rw-rw- myself users 21 1996-09-23 16:44 blues
-rw-rw-rw- myself users 20 1996-09-23 16:44 folk
-rw-rw-rw- myself users 20 1996-09-23 16:44 rock
@end smallexample
@end ignore
@FIXME{The above example is wrong: the long listing is only printed if
you say --verbose. We think the verbose listing should be used only
where required, since most people will see slightly different values
printed for everything but the file names, and newbies might get
confused. So we left the command as it was, but changed the output:}
@smallexample
$ @kbd{tar --list --file=collection.tar}
jazz
blues
folk
rock
@end smallexample
@node Multiple files, , Appending files, append
@subsubsection Multiple files with the same name
You can use @value{append} 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 @code{tar} option called
@value{update}; @pxref{update}, for more information. We describe this
use of @value{append} here for the sake of completeness.)
When you extract the archive, the older version will effectively be lost.
This happens 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 overwrite 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.
Suppose you change the file @file{blues} and then append the changed
version to @file{collection.tar}. As you saw above, the original
@file{blues} is in the archive @file{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 overwritten by the
newer version when it is extracted.
You can append the new, changed copy of the file @file{blues} to the
archive in this way:
@smallexample
$ @kbd{tar --append --verbose --file=collection.tar blues}
blues
@end smallexample
@noindent
Because you specified the @value{verbose} option, @code{tar} has
printed the name of the file being appended as it was acted on. Now
list the contents of the archive:
@smallexample
$ @kbd{tar --list --verbose --file=collection.tar}
-rw-rw-rw- myself users 28 1996-10-18 16:31 jazz
-rw-rw-rw- myself users 21 1996-09-23 16:44 blues
-rw-rw-rw- myself users 20 1996-09-23 16:44 folk
-rw-rw-rw- myself users 20 1996-09-23 16:44 rock
-rw-rw-rw- myself users 58 1996-10-24 18:30 blues
@end smallexample
@noindent
The newest version of @file{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 @file{blues} will be
overwritten by the newer version. You can confirm this by extracting
the archive and running @code{ls} on the directory. @xref{Writing},
for more information. (@emph{Please note:} This is the case unless
you employ the @value{backup} option; @FIXME{ref Multiple Members
with the Same Name}.)
@node update, , append, create
@subsection Updating an archive
@cindex Updating an archive
In the previous section, you learned how to use @value{append} to add
a file to an existing archive. A related subcommand is
@value{update}. The @value{update} subcommand updates a @code{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 @value{append}).
Unfortunately, you cannot use @value{update} with magnetic tape drives.
The command will fail.
Both @value{update} and @value{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 @value{backup} option (@FIXME{ref Multiple Members with the
Same Name}).
@FIXME{It was: A combination of the --compare and --append subcommands.
This is not true and rather misleading, as --compare does a lot more than
--update for ensuring files are identical.}
@menu
* How to update:: How to update members of an archive
* Unsuitability of update:: Updating does not always work
@end menu
@node How to update, Unsuitability of update, update, update
@subsubsection How to update members of an archive
You must use file name arguments with the @value{update} subcommand.
If you don't specify any files, @code{tar} won't act on any files and
won't tell you that it didn't do anything (which might end up confusing
you).
To see the @value{update} option at work, create a new file,
@file{classical}, in your practice directory, and some extra text to the
file @file{blues}, using any text editor. Then invoke @code{tar} with
the @kbd{update} subcommand and the @value{verbose} option specified,
using the names of all the files in the practice directory as file name
arguments:
@smallexample
$ @kbd{tar --update -v -f collection.tar blues folk rock classical}
blues
classical
$
@end smallexample
@noindent
Because we have specified verbose mode, @code{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 @kbd{tar --list} and look
at the archive, you will see @file{blues} and @file{classical} at its
end. There will be a total of two versions of the member @file{blues};
the one at the end will be newer and larger, since you added text before
updating it.
(The reason @code{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 get data inserted in their middle;
doing so would destroy any data after the place you write. @xref{Media},
for more information about tapes.)
@value{update} 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 @code{tar} options intended
specifically for backups are more efficient. If you need to run
backups, please consult @ref{Backups}.
@node Unsuitability of update, , How to update, update
@subsubsection Updating does not always work
Sometimes, you may have a situation for which you would think usign
@value{update} would be ideal; unfortunately, this is not always the
case. Two situations for which @value{update} is unsuitable are
updating an archive stored on a magnetic tape, and making
a backup. Other subcommands and options provide more appropriate
solutions in these situations.
@code{tar} does not overwrite the older file when updating an archive.
This is because writing to the middle of a section of tape is a
difficult process. Tapes are not really designed to go backward
(although some have the capability), and their linear nature makes
inserting data into the middle of a tape impossible, even if there is
room at the end of the tape. In this way, tapes differ from other kinds
of storage media, such as floppy diskettes and hard drives.
@xref{Media}, for more information about tapes and other kinds of storage
media.
@value{update} 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 @code{tar} options intended
specifically for backups are more efficient. If you need to run
backups, please consult @ref{Backups}.
@node Applications, , create, Subcommands
@section Other uses for @code{tar}
@FIXME{Using Unix file linking capability to recreate directory
structures---linking files into one subdirectory and then @code{tar}ring
that directory.}
@findex uuencode
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 @code{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 @code{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 @dfn{pipe}, which is a Unix redirection mechanism:
@smallexample
$ @w{@kbd{cd sourcedir; tar --create --file=- . | (cd targetdir; tar --extract --file=-)}}
@end smallexample
@noindent
The command also works using short option forms:
@smallexample
$ @kbd{cd sourcedir; tar -cf - . | (cd targetdir; tar -xf -)}
@end smallexample
@noindent
If you are really confident you are using @code{tar} and that standard
input and output were not overridden by something else as the default archive
at your installation, you might write the above examples more simply:
@smallexample
$ @kbd{cd sourcedir; tar --create . | (cd targetdir; tar --extract)}
$ @kbd{cd sourcedir; tar -c . | (cd targetdir; tar -x)}
@end smallexample
This is one of the easiest methods to transfer a @code{tar} archive.
@FIXME{Examples to be adjusted for -p, but see about root/non-root first.}
@menu
* concatenate:: Combining archives with @code{tar}
* Using cat with archives:: Combining archives with @code{cat}
* delete:: Removing archive members from an archive
@end menu
@node concatenate, Using cat with archives, Applications, Applications
@subsection Combining archives with @code{tar}
@cindex Adding archives to an archive
@cindex Concatenating Archives
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
the contents of one or more archives to the end of another archive, you
should use the @value{concatenate} subcommand.
To use @value{concatenate}, name two archives to be concatenated on the
command line. (Nothing happens if you don't list any.) The members,
and their member names, will be copied verbatim from those archives. If
this causes multiple members to have the same name, it does not delete
any members; all the members with the same name coexist. For
information on how this affects reading the archive, @FIXME{ref Multiple
Members with the Same Name}.
To demonstrate how @value{concatenate} works, create two small archives
called @file{bluesrock.tar} and @file{folkjazz.tar}, using the relevant
files from @file{practice}:
@smallexample
$ @kbd{tar -cvf bluesrock.tar blues rock}
blues
rock
$ @kbd{tar -cvf folkjazz.tar folk jazz}
folk
jazz
@end smallexample
@noindent
If you like, you can run @kbd{tar --list} to make sure the archives
contain what they are supposed to:
@smallexample
$ @kbd{tar -tvf bluesrock.tar}
-rw-rw-rw- myself users 105 1997-01-21 19:42 blues
-rw-rw-rw- myself users 33 1997-01-20 15:34 rock
$ @kbd{tar -tvf folkjazz.tar}
-rw-rw-rw- myself users 20 1996-09-23 16:44 folk
-rw-rw-rw- myself users 65 1997-01-30 14:15 jazz
@end smallexample
@FIXME{The long listing will only be printed undet -tvvf. See the
remark above about why we think vv should be used as little as
possible.---eliz}
We can concatenate these two archives with @code{tar}:
@ignore
@smallexample
$ @kbd{cd ..}
$ @kbd{tar --concatenate --file=bluesrock.tar jazzfolk.tar}
@end smallexample
@end ignore
@FIXME{why the "cd .." above? We think it's wrong, so we deleted it.}
@smallexample
$ @kbd{tar --concatenate --file=bluesrock.tar jazzfolk.tar}
@end smallexample
If you now list the contents of the @file{bluesrock.tar}, you will see
that now it also contains the archive members of @file{jazzfolk.tar}:
@smallexample
$ @kbd{tar --list --file=bluesrock.tar}
blues
rock
jazz
folk
@end smallexample
When you use @value{concatenate}, the source and target archives must
already exist and must have been created using compatible format parameters
(@FIXME{pxref Matching Format Parameters}). The new, concatenated archive
will be called by the same name as the first archive listed on the command
line. @FIXME{Is there a way to specify a new name? Of course, there is:
set $TAPE to the new name, and use --concatenate with no --file= argument.}
Like @value{append}, this subcommand cannot be performed on some
tape drives, due to deficiencies in the formats those tape drives use.
@cindex @code{concatenate} vs @code{cat}
@cindex @code{cat} vs @code{concatenate}
It may seem more intuitive to you to try to use @code{cat} to
concatenate two archives instead of using the @value{concatenate}
subcommand; after all, @code{cat} is the utility for combining files.
However, @code{tar} archives incorporate an end-of-file marker which
must be removed if the concatenated archives are to be read properly as
one archive. @value{concatenate} removes the end-of-archive marker
from the target archive before each new archive is appended. If you use