mirrors/tar
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Udated

Browse Source
This commit is contained in:
Sergey Poznyakoff
2004-05-05 11:55:18 +00:00
parent 45399a7e81
commit de5ec134a1
2 changed files with 206 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
TODO
View File

@@ -3,7 +3,7 @@ Suggestions for improving GNU tar.
* Incorporate fixes from major distributions, e.g., Debian GNU/Linux.
* Add support for GNU private keywords in POSIX 1003.1-2001 headers,
so that the GNU extensions (--sparse, --incremental, --label and
so that the GNU extensions (--incremental, --label and
--multi-volume) may be used with POSIX archives.
* Add support for a 'pax' command that conforms to POSIX 1003.1-2001.

265
doc/tar.texi
View File

@@ -46,7 +46,7 @@
@c do not alter them inconsiderately. Much work is needed for GNU tar
@c internals (the sources, the programs themselves). Revising the
@c adequacy of the manual while revising the sources, and cleaning them
@c both at the same time, seems to him like a good way to proceed.
@c both at the same time, is a good way to proceed.
@c ---------------------------------------------------------------------
@c Output marks for nodes needing revision, but not in PUBLISH rendition.
@@ -262,9 +262,14 @@
@set pxref-interactive @pxref{interactive}
@set op-keep-old-files @kbd{--keep-old-files} (@kbd{-k})
@set ref-keep-old-files @ref{Writing}
@set xref-keep-old-files @xref{Writing}
@set pxref-keep-old-files @pxref{Writing}
@set ref-keep-old-files @ref{Keep Old Files}
@set xref-keep-old-files @xref{Keep Old Files}
@set pxref-keep-old-files @pxref{Keep Old Files}
@set op-keep-newer-files @kbd{--keep-old-files}
@set ref-keep-newer-files @ref{Keep Newer Files}
@set xref-keep-newer-files @xref{Keep Newer Files}
@set pxref-keep-newer-files @pxref{Keep Newer Files}
@set op-label @kbd{--label=@var{archive-label}} (@kbd{-V @var{archive-label}})
@set ref-label @ref{label}
@@ -696,6 +701,7 @@ Changing How @command{tar} Writes Files
* Dealing with Old Files::
* Overwrite Old Files::
* Keep Old Files::
* Keep Newer Files::
* Unlink First::
* Recursive Unlink::
* Modification Times::
@@ -821,7 +827,7 @@ Copying This Manual
@chapter Introduction
@GNUTAR{} creates
and manipulates (@dfn{archives}) which are actually collections of
and manipulates @dfn{archives} which are actually collections of
many other files; the program provides users with an organized and
systematic method for controlling a large amount of data.
The name ``tar'' originally came from the phrase ``Tape ARchive'', but
@@ -876,7 +882,7 @@ entirety in other @acronym{GNU} manuals, and is mostly self-contained.
In addition, one section of this manual (@pxref{Standard}) contains a
big quote which is taken directly from @command{tar} sources.
In general, we give both the long and short (abbreviated) option names
In general, we give both long and short (abbreviated) option names
at least once in each section where the relevant option is covered, so
that novice readers will become familiar with both styles. (A few
options have no short versions, and the relevant sections will
@@ -1010,14 +1016,17 @@ primary aims are:
@item Improve compatibility between @GNUTAR{} and other @command{tar}
implementations.
@item Switch to using @acronym{POSIX} archives.
@item Revise sparse file handling.
@item Revise multiple volume processing.
@item Revise sparse file handling and multiple volume processing.
@item Merge with the @acronym{GNU} @code{paxutils} project.
@end itemize
The following issues need mentioning:
Some of these aims are already attained, while others are still
being worked upon. From the point of view of an end user, the
following issues need special mentioning:
@table @asis
@item Use of short option @option{-o}.
Earlier versions of @GNUTAR{} understood @option{-o} command line
option as a synonym for @option{--old-archive}.
@@ -1029,10 +1038,16 @@ However, to facilitate transition, @option{-o} option retains its
old semantics when it is used with one of archive-creation commands.
Users are encouraged to use @value{op-format-oldgnu} instead.
It is especially important, since versions of @acronym{GNU} Automake
up to and including 1.8.4 invoke tar with this option to produce
distribution tarballs. @xref{Formats,v7}, for the detailed discussion
of this issue and its implications.
Future versions of @GNUTAR{} will understand @option{-o} only as a
synonym for @option{--no-same-owner}.
synonym for @option{--no-same-owner}.
@item Use of short option @option{-l}
Earlier versions of @GNUTAR{} understood @option{-l} option as a
synonym for @samp{--one-file-system}. Such usage is deprecated.
For compatibility with other implementations future versions of
@@ -1040,9 +1055,11 @@ For compatibility with other implementations future versions of
@option{--check-links}.
@item Use of options @option{--portability} and @option{--old-archive}
These options are deprecated. Please use @option{--format=v7} instead.
@item Use of option @option{--posix}
This option is deprecated. Please use @option{--format=posix} instead.
@end table
@@ -1052,8 +1069,9 @@ This option is deprecated. Please use @option{--format=posix} instead.
@GNUTAR{} was originally written by John Gilmore,
and modified by many people. The @acronym{GNU} enhancements were
written by Jay Fenlason, then Joy Kendall, and the whole package has
been further maintained by Thomas Bushnell, n/BSG, and finally
Fran@,{c}ois Pinard, with the help of numerous and kind users.
been further maintained by Thomas Bushnell, n/BSG, Fran@,{c}ois
Pinard, Paul Eggert, and finally Sergey Poznyakoff with the help of
numerous and kind users.
We wish to stress that @command{tar} is a collective work, and owes much to
all those people who reported problems, offered solutions and other
@@ -1099,6 +1117,11 @@ Support for @acronym{POSIX} archives was added by Sergey Poznyakoff.
If you find problems or have suggestions about this program or manual,
please report them to @file{bug-tar@@gnu.org}.
When reporting a bug, please be sure to include as much detail as
possible, in order to reproduce it. @FIXME{Be more specific, I'd
like to make this node as detailed as 'Bug reporting' node in Emacs
manual}.
@node Tutorial
@chapter Tutorial Introduction to @command{tar}
@@ -1175,14 +1198,10 @@ In the examples, @samp{$} represents a typical shell prompt. It
precedes lines you should type; to make this more clear, those lines are
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}. When we have lines which are too long to be
displayed in any other way, we will show them like this:
sometimes @samp{like this}.
@smallexample
This is an example of a line which would otherwise not fit in this space.
@end smallexample
@FIXME{how often do we use smallexample?}
@c When we have lines which are too long to be
@c displayed in any other way, we will show them like this:
@node basic tar options
@section Basic @command{tar} Operations and Options
@@ -1216,7 +1235,7 @@ you used to seeing them. (Note that the ``old style'' option forms
exist in @GNUTAR{} for compatibility with Unix
@command{tar}. We present a full discussion of this way of writing
options and operations appears in @ref{Old Options}, and we discuss
the other two styles of writing options in @ref{Mnemonic Options} and
the other two styles of writing options in @ref{Mnemonic Options}, and
@ref{Short Options}.)
In the examples and in the text of this tutorial, we usually use the
@@ -1509,7 +1528,7 @@ and @file{jazz}, are now members of the archive, @file{collection.tar}
(they are @dfn{file name arguments} to the @samp{--create} operation).
@FIXME{xref here to the discussion of file name args?}Now that they are
in the archive, they are called @emph{archive members}, not files.
@FIXME{xref to definitions?}
(@pxref{Definitions,members}).
When you create an archive, you @emph{must} specify which files you
want placed in the archive. If you do not specify any archive
@@ -1803,12 +1822,6 @@ stored in the specified archive.
@node list dir
@unnumberedsubsec Listing the Contents of a Stored Directory
@UNREVISED
@FIXME{i changed the order of these nodes around and haven't had a
chance to play around with this node's example, yet. i have to play
with it and see what it actually does for my own satisfaction, even if
what it says *is* correct..}
To get information about the contents of an archived directory,
use the directory name as a file name argument in conjunction with
@@ -1891,8 +1904,10 @@ arguments, as printed by @value{op-list}. If you had mistakenly deleted
one of the files you had placed in the archive @file{collection.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{check this; will the times,
permissions, owner, etc be the same, also?}
file @file{blues} that you deleted. @FIXME{At the time of this
writing, atime and ctime are not restored. Since this is a tutorial
for a beginnig user, it should hardly be mentioned here. Maybe in
a footnote? --gray}.
First, make sure you are in the @file{practice} directory, and list the
files in the directory. Now, delete the file, @samp{blues}, and list
@@ -1930,7 +1945,7 @@ exact member names of the members of an archive, use @value{op-list}
(@pxref{list}).
You can extract a file to standard output by combining the above options
with the @option{--to-stdout} option (@pxref{Writing to Standard
with the @value{op-to-stdout} option (@pxref{Writing to Standard
Output}).
If you give the @value{op-verbose} option, then @value{op-extract} will
@@ -1948,7 +1963,9 @@ files in the pre-existing directory with the same names as the members
which you extract, the files from the extracted archive will replace
the files already in the working directory (and possible
subdirectories). This will happen regardless of whether or not the
files in the working directory were more recent than those extracted.
files in the working directory were more recent than those extracted
(there exist, however, special options that alter this behavior
@pxref{Writing}).
However, if a file was stored with a directory name as part of its file
name, and that directory does not exist under the working directory when
@@ -1966,11 +1983,20 @@ following command:
@smallexample
$ @kbd{tar -xvf music.tar practice/folk practice/jazz}
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. have to write that up
(should be trivial, but i'm too tired!).}
@noindent
If you were to specify two @value{op-verbose} options, @command{tar}
would have displayed more detail about the extracted files, as shown
in the example below:
@smallexample
$ @kbd{tar -xvvf music.tar practice/folk practice/jazz}
-rw-rw-rw- me user 28 1996-10-18 16:31 practice/jazz
-rw-rw-rw- me user 20 1996-09-23 16:44 practice/folk
@end smallexample
@noindent
Because you created the directory with @file{practice} as part of the
@@ -1998,6 +2024,10 @@ $ @kbd{cd newdir}
$ @kbd{tar -xvf ../untrusted.tar}
@end smallexample
It is also a good practice to examine contents of the archive
before extracting it, using @option{op-list} option, possibly combined
with @option{op-verbose}.
@node failing commands
@subsection Commands That Will Fail
@@ -2254,8 +2284,12 @@ number of important files. We urge you to note these differences, and
only use the option style(s) which makes the most sense to you until you
feel comfortable with the others.
@FIXME{hag to write a brief paragraph on the option(s) which can
optionally take an argument}
Some options @emph{may} take an argument (currently, there are
two such options: @value{op-backup} and @value{op-occurrence}). Such
options may have at most long and short forms, they do not have old style
equivalent. The rules for specifying an argument for such options
are stricter than those for specifying mandatory arguments. Please,
pay special attention to them.
@menu
* Mnemonic Options:: Mnemonic Option Style
@@ -2299,11 +2333,18 @@ gives a fairly good set of hints about what the command does, even
for those not fully acquainted with @command{tar}.
Mnemonic options which require arguments take those arguments
immediately following the option name; they are introduced by an equal
sign. For example, the @samp{--file} option (which tells the name
of the @command{tar} archive) is given a file such as @file{archive.tar}
as argument by using the notation @samp{--file=archive.tar} for the
mnemonic option.
immediately following the option name. There are two ways of
specifying a mandatory argument. It can be separated from the
option name either by an equal sign, or by any amount of
white space characters. For example, the @samp{--file} option (which
tells the name of the @command{tar} archive) is given a file such as
@file{archive.tar} as argument by using any of the following notations:
@samp{--file=archive.tar} or @samp{--file archive.tar}.
In contrast, optional arguments must always be introduced using
an equal sign. For example, the @samp{--backup} option takes
an optional argument specifying backup type. It must be used
as @samp{--backup=@var{backup-type}}.
@node Short Options
@subsection Short Option Style
@@ -2324,6 +2365,10 @@ archive.tar}} or @samp{-farchive.tar} instead of using
@w{@samp{-f @var{archive-name}}} denote the option which indicates a
specific archive, here named @file{archive.tar}.
Short options which take optional arguments take their arguments
immediately following the option letter, @emph{without any intervening
white space characters}.
Short options' letters may be clumped together, but you are not
required to do this (as compared to old options; see below). When
short options are clumped as a set, use one (single) dash for them
@@ -2401,7 +2446,7 @@ users. For example, the two commands:
are quite different. The first example uses @file{archive.tar.gz} as
the value for option @samp{f} and recognizes the option @samp{z}. The
second example, however, uses @file{z} as the value for option
@samp{f}---probably not what was intended.
@samp{f} --- probably not what was intended.
Old options are kept for compatibility with old versions of @command{tar}.
@@ -2740,6 +2785,8 @@ Creates a POSIX.1-2001 archive.
@end table
@xref{Formats}, for a detailed discussion of these formats.
@item --group=@var{group}
Files added to the @command{tar} archive will have a group id of @var{group},
@@ -2805,6 +2852,11 @@ Specifies that @command{tar} should ask the user for confirmation before
performing potentially destructive options, such as overwriting files.
@FIXME-xref{}
@item --keep-newer-files
Do not replace existing files that are newer than their archive copies
when extracting files from an archive.
@item --keep-old-files
@itemx -k
@@ -3177,6 +3229,17 @@ effect only for ordinary users. @FIXME-xref{}
(See @samp{--preserve-permissions}; @pxref{Writing}.)
@item --show-defaults
Displays the default options used by @command{tar} and exits
successfully. This option is intended for use in shell scripts.
Here is an example of what you can see using this option:
@smallexample
$ tar --show-defaults
--format=gnu -f- -b20
@end smallexample
@item --show-omitted-dirs
Instructs @command{tar} to mention directories its skipping over when
@@ -3255,6 +3318,11 @@ system before extracting it from the archive. @xref{Writing}.
Instructs @command{tar} to access the archive through @var{prog}, which is
presumed to be a compression program of some sort. @FIXME-xref{}
@item --utc
Display file modification dates in @acronym{UTC}. This option implies
@samp{--verbose}.
@item --verbose
@itemx -v
@@ -3970,7 +4038,7 @@ this really a good idea, to give this whole description for something
which i believe is basically a Stupid way of doing something? certain
aspects of it show ways in which tar is more broken than i'd personally
like to admit to, specifically the last sentence. On the other hand, i
don't think it's a good idea to be saying that re explicitly don't
don't think it's a good idea to be saying that we explicitly don't
recommend using something, but i can't see any better way to deal with
the situation.}When you extract the archive, the older version will be
effectively lost. This works because files are extracted from an
@@ -4433,6 +4501,7 @@ encountered while reading an archive. Use in conjunction with
* Dealing with Old Files::
* Overwrite Old Files::
* Keep Old Files::
* Keep Newer Files::
* Unlink First::
* Recursive Unlink::
* Modification Times::
@@ -4531,6 +4600,15 @@ Prevents @command{tar} from replacing files in the file system during
extraction.
@end table
@node Keep Newer Files
@unnumberedsubsubsec Keep Newer Files
@table @kbd
@item --keep-newer-files
Do not replace existing files that are newer than their archive
copies. This option is meaningless with @value{op-list}.
@end table
@node Unlink First
@unnumberedsubsubsec Unlink First
@@ -4839,7 +4917,6 @@ $ @kbd{cd sourcedir; tar -cf - . | (cd targetdir; tar -xf -)}
@noindent
The command also works using short option forms:
@FIXME{The following using standard input/output correct??}
@smallexample
$ @w{@kbd{cd sourcedir; tar --create --file=- . | (cd targetdir; tar --extract --file=-)}}
@end smallexample
@@ -6300,24 +6377,91 @@ The most frequently used formats are (in alphabetical order):
@table @asis
@item gnu
Format used by @GNUTAR{}.
Format used by @GNUTAR{} versions up to 1.13.25. This format derived
from an early POSIX standard, adding some improvements such as
sparse file handling and incremental archives. Unfortunately these
features were implemented in a way incompatible with other archive
formats.
@item v7
Archive format, compatible with the V7 implementation of tar.
Archives in @samp{gnu} format are able to hold pathnames of unlimited
length.
@item oldgnu
Format used by @GNUTAR{} of versions prior to 1.12.
@item posix
Archive format defined by POSIX.1-2001 specification.
@item v7
Archive format, compatible with the V7 implementation of tar. This
format imposes a number of limitations. The most important of them
are:
@enumerate
@item The maximum length of a file name is limited to 99 characters.
@item The maximum length of a symbolic link is limited to 99 characters.
@item It is impossible to store special files (block and character
devices, fifos etc.)
@item Maximum value of user or group ID is limited to 2097151 (7777777
octal)
@item V7 archives do not contain symbolic ownership information (user
and group name of the file owner).
@end enumerate
This format has traditionally been used by Automake when producing
Makefiles. This practice will change in the future, in the meantime,
however this means that projects containing filenames more than 99
characters long will not be able to use @GNUTAR{} @value{VERSION} and
Automake prior to 1.9.
@item ustar
Archive format defined by POSIX.1-1988 specification. It stores
symbolic ownership information. It is also able to store
special files. However, it imposes several restrictions as well:
@enumerate
@item The maximum length of a file name is limited to 256 characters,
provided that the filename can be split at directory separator in
two parts, first of them being at most 155 bytes long. So, in most
cases the maximum file name length will be shorter than 256
characters.
@item The maximum length of a symbolic link name is limited to
100 characters.
@item Maximum size of a file the archive is able to accomodate
is 8GB
@item Maximum value of UID/GID is 2097151.
@item Maximum number of bits in device major and minor numbers is 21.
@end enumerate
@item star
Format used by J@"org Schilling @command{star} implementation.
Format used by J@"org Schilling @command{star}
implementation. @GNUTAR{} is able to read @samp{star} archives but
currently does not produce them.
@item posix
Archive format defined by POSIX.1-2001 specification. This is the
most flexible and feature-rich format. It does not impose any
restrictions on file sizes or filename lengths. This format is quite
recent, so not all tar implementations are able to handle it properly.
However, this format is designed in such a way that any tar
implementation able to read @samp{ustar} archives will be able to read
most @samp{posix} archives as well, with the only exception that any
additional information (such as long file names etc.) will in such
case be extracted as plain text files along with the files it refers to.
This archive format will be the default format for future versions
of @GNUTAR{}.
@end table
@GNUTAR{} is able to create archives in any of these formats,
except @samp{star}. It is able to read archives in any of these
formats.
The following table summarizes the limitations of each of these
formats:
@multitable @columnfractions .10 .20 .20 .20 .20
@item Format @tab UID @tab File Size @tab Path Name @tab Devn
@item gnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63
@item oldgnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63
@item v7 @tab 2097151 @tab 8GB @tab 99 @tab n/a
@item ustar @tab 2097151 @tab 8GB @tab 256 @tab 21
@item posix @tab Unlimited @tab Unlimited @tab Unlimited @tab Unlimited
@end multitable
The default format for @GNUTAR{} is defined at compilation
time. You may check it by running @command{tar --help}, and examining
@@ -6975,7 +7119,7 @@ It is equivalent to @value{op-same-permissions} plus @value{op-same-order}.
@end table
@node Standard
@section The Standard Format
@section Basic Tar Format
@UNREVISED
While an archive may contain many files, the archive itself is a
@@ -6987,7 +7131,8 @@ manipulate without using the @command{tar} utility or Tar mode in
@acronym{GNU} Emacs.
Physically, an archive consists of a series of file entries terminated
by an end-of-archive entry, which consists of 512 zero bytes. A file
by an end-of-archive entry, which consists of two 512 blocks of zero
bytes. A file
entry usually describes one of the files in the archive (an
@dfn{archive member}), and consists of a file header and the contents
of the file. File headers contain file names and statistics, checksum
@@ -7011,10 +7156,11 @@ of as being on magnetic tape, other media are often used.
Each file archived is represented by a header block which describes
the file, followed by zero or more blocks which give the contents
of the file. At the end of the archive file there may be a block
of the file. At the end of the archive file there are two 512-byte blocks
filled with binary zeros as an end-of-file marker. A reasonable system
should write a block of zeros at the end, but must not assume that
such a block exists when reading an archive.
should write such end-of-file marker at the end of an archive, but
must not assume that such a block exists when reading an archive. In
particular @GNUTAR{} always issues a warning if it does not encounter it.
The blocks may be @dfn{blocked} for physical I/O operations.
Each record of @var{n} blocks (where @var{n} is set by the
@@ -7049,8 +7195,7 @@ of file contents is performed.
The @code{name}, @code{linkname}, @code{magic}, @code{uname}, and
@code{gname} are null-terminated character strings. All other fields
are zero-filled octal numbers in ASCII. Each numeric field of width
@var{w} contains @var{w} minus 2 digits, a space, and a null, except
@code{size}, and @code{mtime}, which do not contain the trailing null.
@var{w} contains @var{w} minus 1 digits, and a null.
The @code{name} field is the file name of the file, with directory names
(if any) preceding the file name, separated by slashes.