code:
@c This is part of the paxutils manual.
@c Copyright (C) 2006 Free Software Foundation, Inc.
@c This file is distributed under GFDL 1.1 or any later version
@c published by the Free Software Foundation.

@menu
* Standard::           Basic Tar Format
* Extensions::         @acronym{GNU} Extensions to the Archive Format
* Sparse Formats::     Storing Sparse Files
* Snapshot Files::
* Dumpdir::
@end menu

@node Standard
@unnumberedsec Basic Tar Format
@UNREVISED

While an archive may contain many files, the archive itself is a
single ordinary file.  Like any other file, an archive file can be
written to a storage device such as a tape or disk, sent through a
pipe or over a network, saved on the active file system, or even
stored in another archive.  An archive file is not easy to read or
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 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
information which @command{tar} uses to detect file corruption, and
information about file types.

Archives are permitted to have more than one member with the same
member name.  One way this situation can occur is if more than one
version of a file has been stored in the archive.  For information
about adding new versions of a file to an archive, see @ref{update}.
@FIXME-xref{To learn more about having more than one archive member with the
same name, see -backup node, when it's written.}

In addition to entries describing archive members, an archive may
contain entries which @command{tar} itself uses to store information.
@xref{label}, for an example of such an archive entry.

A @command{tar} archive file contains a series of blocks.  Each block
contains @code{BLOCKSIZE} bytes.  Although this format may be thought
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 are two 512-byte blocks
filled with binary zeros as an end-of-file marker.  A reasonable system
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
@option{--blocking-factor=@var{512-size}} (@option{-b @var{512-size}}) option to @command{tar}) is written with a single
@w{@samp{write ()}} operation.  On magnetic tapes, the result of
such a write is a single record.  When writing an archive,
the last record of blocks should be written at the full size, with
blocks after the zero block containing all zeros.  When reading
an archive, a reasonable system should properly handle an archive
whose last record is shorter than the rest, or which contains garbage
records after a zero block.

The header block is defined in C as follows.  In the @GNUTAR{}
distribution, this is part of file @file{src/tar.h}:

@smallexample
@include header.texi
@end smallexample

All characters in header blocks are represented by using 8-bit
characters in the local variant of ASCII.  Each field within the
structure is contiguous; that is, there is no padding used within
the structure.  Each character on the archive medium is stored
contiguously.

Bytes representing the contents of files (after the header block
of each file) are not translated in any way and are not constrained
to represent characters in any character set.  The @command{tar} format
does not distinguish text files from binary files, and no translation
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 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.

@FIXME{how big a name before field overflows?}

The @code{mode} field provides nine bits specifying file permissions
and three bits to specify the Set UID, Set GID, and Save Text
(@dfn{sticky}) modes.  Values for these bits are defined above.
When special permissions are required to create a file with a given
mode, and the user restoring files from the archive does not hold such
permissions, the mode bit(s) specifying those special permissions
are ignored.  Modes which are not supported by the operating system
restoring files from the archive will be ignored.  Unsupported modes
should be faked up when creating or updating an archive; e.g., the
group permission could be copied from the @emph{other} permission.

The @code{uid} and @code{gid} fields are the numeric user and group
ID of the file owners, respectively.  If the operating system does
not support numeric user or group IDs, these fields should be ignored.

The @code{size} field is the size of the file in bytes; linked files
are archived with this field specified as zero.  @FIXME-xref{Modifiers, in
particular the @option{--incremental} (@option{-G}) option.}

The @code{mtime} field is the data modification time of the file at
the time it was archived.  It is the ASCII representation of the octal
value of the last time the file's contents were modified, represented
as an integer number of
seconds since January 1, 1970, 00:00 Coordinated Universal Time.

The @code{chksum} field is the ASCII representation of the octal value
of the simple sum of all bytes in the header block.  Each 8-bit
byte in the header is added to an unsigned integer, initialized to
zero, the precision of which shall be no less than seventeen bits.
When calculating the checksum, the @code{chksum} field is treated as
if it were all blanks.

The @code{typeflag} field specifies the type of file archived.  If a
particular implementation does not recognize or permit the specified
type, the file will be extracted as if it were a regular file.  As this
action occurs, @command{tar} issues a warning to the standard error.

The @code{atime} and @code{ctime} fields are used in making incremental
backups; they store, respectively, the particular file's access and
status change times.

The @code{offset} is used by the @option{--multi-volume} (@option{-M}) option, when
making a multi-volume archive.  The offset is number of bytes into
the file that we need to restart at to continue the file on the next
tape, i.e., where we store the location that a continued file is
continued at.

The following fields were added to deal with sparse files.  A file
is @dfn{sparse} if it takes in unallocated blocks which end up being
represented as zeros, i.e., no useful data.  A test to see if a file
is sparse is to look at the number blocks allocated for it versus the
number of characters in the file; if there are fewer blocks allocated
for the file than would normally be allocated for a file of that
size, then the file is sparse.  This is the method @command{tar} uses to
detect a sparse file, and once such a file is detected, it is treated
differently from non-sparse files.

Sparse files are often @code{dbm} files, or other database-type files
which have data at some points and emptiness in the greater part of
the file.  Such files can appear to be very large when an @samp{ls
-l} is done on them, when in truth, there may be a very small amount
of important data contained in the file.  It is thus undesirable
to have @command{tar} think that it must back up this entire file, as
great quantities of room are wasted on empty blocks, which can lead
to running out of room on a tape far earlier than is necessary.
Thus, sparse files are dealt with so that these empty blocks are
not written to the tape.  Instead, what is written to the tape is a
description, of sorts, of the sparse file: where the holes are, how
big the holes are, and how much data is found at the end of the hole.
This way, the file takes up potentially far less room on the tape,
and when the file is extracted later on, it will look exactly the way
it looked beforehand.  The following is a description of the fields
used to handle a sparse file:

The @code{sp} is an array of @code{struct sparse}.  Each @code{struct
sparse} contains two 12-character strings which represent an offset
into the file and a number of bytes to be written at that offset.
The offset is absolute, and not relative to the offset in preceding
array element.

The header can hold four of these @code{struct sparse} at the moment;
if more are needed, they are not stored in the header.

The @code{isextended} flag is set when an @code{extended_header}
is needed to deal with a file.  Note that this means that this flag
can only be set when dealing with a sparse file, and it is only set
in the event that the description of the file will not fit in the
allotted room for sparse structures in the header.  In other words,
an extended_header is needed.

The @code{extended_header} structure is used for sparse files which
need more sparse structures than can fit in the header.  The header can
fit 4 such structures; if more are needed, the flag @code{isextended}
gets set and the next block is an @code{extended_header}.

Each @code{extended_header} structure contains an array of 21
sparse structures, along with a similar @code{isextended} flag
that the header had.  There can be an indeterminate number of such
@code{extended_header}s to describe a sparse file.

@table @asis

@item @code{REGTYPE}
@itemx @code{AREGTYPE}
These flags represent a regular file.  In order to be compatible
with older versions of @command{tar}, a @code{typeflag} value of
@code{AREGTYPE} should be silently recognized as a regular file.
New archives should be created using @code{REGTYPE}.  Also, for
backward compatibility, @command{tar} treats a regular file whose name
ends with a slash as a directory.

@item @code{LNKTYPE}
This flag represents a file linked to another file, of any type,
previously archived.  Such files are identified in Unix by each
file having the same device and inode number.  The linked-to name is
specified in the @code{linkname} field with a trailing null.

@item @code{SYMTYPE}
This represents a symbolic link to another file.  The linked-to name
is specified in the @code{linkname} field with a trailing null.

@item @code{CHRTYPE}
@itemx @code{BLKTYPE}
These represent character special files and block special files
respectively.  In this case the @code{devmajor} and @code{devminor}
fields will contain the major and minor device numbers respectively.
Operating systems may map the device specifications to their own
local specification, or may ignore the entry.

@item @code{DIRTYPE}
This flag specifies a directory or sub-directory.  The directory
name in the @code{name} field should end with a slash.  On systems where
disk allocation is performed on a directory basis, the @code{size} field
will contain the maximum number of bytes (which may be rounded to
the nearest disk block allocation unit) which the directory may
hold.  A @code{size} field of zero indicates no such limiting.  Systems
which do not support limiting in this manner should ignore the
@code{size} field.

@item @code{FIFOTYPE}
This specifies a FIFO special file.  Note that the archiving of a
FIFO file archives the existence of this file and not its contents.

@item @code{CONTTYPE}
This specifies a contiguous file, which is the same as a normal
file except that, in operating systems which support it, all its
space is allocated contiguously on the disk.  Operating systems
which do not allow contiguous allocation should silently treat this
type as a normal file.

@item @code{A} @dots{} @code{Z}
These are reserved for custom implementations.  Some of these are
used in the @acronym{GNU} modified format, as described below.

@end table

Other values are reserved for specification in future revisions of
the P1003 standard, and should not be used by any @command{tar} program.

The @code{magic} field indicates that this archive was output in
the P1003 archive format.  If this field contains @code{TMAGIC},
the @code{uname} and @code{gname} fields will contain the ASCII
representation of the owner and group of the file respectively.
If found, the user and group IDs are used rather than the values in
the @code{uid} and @code{gid} fields.

For references, see ISO/IEC 9945-1:1990 or IEEE Std 1003.1-1990, pages
169-173 (section 10.1) for @cite{Archive/Interchange File Format}; and
IEEE Std 1003.2-1992, pages 380-388 (section 4.48) and pages 936-940
(section E.4.48) for @cite{pax - Portable archive interchange}.

@node Extensions
@unnumberedsec @acronym{GNU} Extensions to the Archive Format
@UNREVISED

The @acronym{GNU} format uses additional file types to describe new types of
files in an archive.  These are listed below.

@table @code
@item GNUTYPE_DUMPDIR
@itemx 'D'
This represents a directory and a list of files created by the
@option{--incremental} (@option{-G}) option.  The @code{size} field gives the total
size of the associated list of files.  Each file name is preceded by
either a @samp{Y} (the file should be in this archive) or an @samp{N}.
(The file is a directory, or is not stored in the archive.)  Each file
name is terminated by a null.  There is an additional null after the
last file name.

@item GNUTYPE_MULTIVOL
@itemx 'M'
This represents a file continued from another volume of a multi-volume
archive created with the @option{--multi-volume} (@option{-M}) option.  The original
type of the file is not given here.  The @code{size} field gives the
maximum size of this piece of the file (assuming the volume does
not end before the file is written out).  The @code{offset} field
gives the offset from the beginning of the file where this part of
the file begins.  Thus @code{size} plus @code{offset} should equal
the original size of the file.

@item GNUTYPE_SPARSE
@itemx 'S'
This flag indicates that we are dealing with a sparse file.  Note
that archiving a sparse file requires special operations to find
holes in the file, which mark the positions of these holes, along
with the number of bytes of data to be found after the hole.

@item GNUTYPE_VOLHDR
@itemx 'V'
This file type is used to mark the volume header that was given with
the @option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) option when the archive was created.  The @code{name}
field contains the @code{name} given after the @option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) option.
The @code{size} field is zero.  Only the first file in each volume
of an archive should have this type.

@end table

You may have trouble reading a @acronym{GNU} format archive on a
non-@acronym{GNU} system if the options @option{--incremental} (@option{-G}),
@option{--multi-volume} (@option{-M}), @option{--sparse} (@option{-S}), or @option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) were
used when writing the archive.  In general, if @command{tar} does not
use the @acronym{GNU}-added fields of the header, other versions of
@command{tar} should be able to read the archive.  Otherwise, the
@command{tar} program will give an error, the most likely one being a
checksum error.

@node Sparse Formats
@unnumberedsec Storing Sparse Files
@include sparse.texi

@node Snapshot Files
@unnumberedsec Format of the Incremental Snapshot Files
@include snapshot.texi

@node Dumpdir
@unnumberedsec Dumpdir
@include dumpdir.texi


code:
@c This is part of GNU tar manual.
@c Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
@c 2003, 2004, 2006 Free Software Foundation, Inc.
@c See file tar.texi for copying conditions.

@c This file contains support for 'renditions' by Fran@,{c}ois Pinard
@c I extended it by adding a FIXME_FOOTNOTE variable, which controls
@c whether FIXME information should be placed in footnotes or
@c inlined. --gray

@c ======================================================================
@c This document has three levels of rendition: PUBLISH, DISTRIB or PROOF,
@c as decided by @set symbols.  The PUBLISH rendition does not show
@c notes or marks asking for revision.  Most users will prefer having more
@c information, even if this information is not fully revised for adequacy,
@c so DISTRIB is the default for distributions.  The PROOF rendition
@c show all marks to the point of ugliness, but is nevertheless useful to
@c those working on the manual itself.
@c ======================================================================

@c Set this symbol if you wish FIXMEs to appear in footnotes, instead
@c of being inserted into the text.
@c @set PROOF_FOOTNOTED

@ifclear PUBLISH
@ifclear DISTRIB
@ifclear PROOF
@set DISTRIB
@end ifclear
@end ifclear
@end ifclear

@ifset PUBLISH
@set RENDITION The book, version
@end ifset

@ifset DISTRIB
@set RENDITION FTP release, version
@end ifset

@ifset PROOF
@set RENDITION Proof reading version
@end ifset

@c Output marks for nodes needing revision, but not in PUBLISH rendition.

@macro UNREVISED
@ifclear PUBLISH
@quotation
@emph{(This message will disappear, once this node revised.)}
@end quotation
@end ifclear
@end macro

@c Output various FIXME information only in PROOF rendition.

@macro FIXME{string}
@allow-recursion
@quote-arg
@ifset PROOF
@ifset PROOF_FOOTNOTED
@footnote{@strong{FIXME:} \string\}
@end ifset
@ifclear PROOF_FOOTNOTED
@cartouche
@strong{<FIXME>} \string\ @strong{</>}
@end cartouche
@end ifclear
@end ifset

@end macro

@macro FIXME-ref{string}
@quote-arg
@ifset PROOF
@strong{<REF>} \string\ @strong{</>}
@end ifset
@end macro

@macro FIXME-pxref{string}
@quote-arg
@ifset PROOF
@strong{<PXREF>} \string\ @strong{</>}
@end ifset

@end macro

@macro FIXME-xref{string}
@quote-arg
@ifset PROOF
@strong{<XREF>} \string\ @strong{</>}
@end ifset
@end macro

@c End of rendition.texi

repo_name: mthl/texinfo

license: mit


code:
@c This is part of the paxutils manual.
@c Copyright (C) 2005 Free Software Foundation, Inc.
@c Written by Sergey Poznyakoff
@c This file is distributed under GFDL 1.1 or any later version
@c published by the Free Software Foundation.

  A @dfn{snapshot file} (or @dfn{directory file}) is created during
incremental backups (@pxref{Incremental Dumps}).  It
contains the status of the filesystem at the time of the dump and is
used to determine which files were modified since the last backup.

  @GNUTAR{} version @value{VERSION} supports two snapshot file
formats.  The first format, called @dfn{format 0}, is the one used by
@GNUTAR{} versions up to 1.15.1. The second format, called @dfn{format
1} is an extended version of this format, that contains more metadata
and allows for further extensions.

  @samp{Format 0} snapshot file begins with a line containing a
decimal number that represents the UNIX timestamp of the beginning of
the last archivation. This line is followed by directory metadata
descriptions, one per line. Each description has the following format:

@smallexample
[@var{nfs}]@var{dev} @var{inode} @var{name}
@end smallexample

@noindent
where optional @var{nfs} is a single plus character (@samp{+}) if this
directory is located on an NFS-mounted partition, @var{dev} and
@var{inode} are the device and inode numbers of the directory, and
@var{name} is the directory name.

  @samp{Format 1} snapshot file begins with a line specifying the
format of the file. This line has the following structure:

@smallexample
@samp{GNU tar-}@var{tar-version}@samp{-}@var{incr-format-version}
@end smallexample

@noindent
where @var{tar-version} is the version of @GNUTAR{} implementation
that created this snapshot, and @var{incr-format-version} is the
version number of the snapshot format (in this case @samp{1}).

  The following line contains two decimal numbers, representing the
time of the last backup. First number is the number of seconds, the
second one is the number of nanoseconds, since the beginning of the
epoch.

  Following lines contain directory metadate, one line per
directory. The line format is:

@smallexample
[@var{nfs}]@var{mtime-sec} @var{mtime-nsec} @var{dev} @var{inode} @var{name}
@end smallexample

@noindent
where @var{mtime-sec} and @var{mtime-nsec} represent the last
modification time of this directory with nanosecond precision;
@var{nfs}, @var{dev}, @var{inode} and @var{name} have the same meaning
as with @samp{format 0}.

@c End of snapshot.texi


code:
@c This is part of the paxutils manual.
@c Copyright (C) 2006 Free Software Foundation, Inc.
@c This file is distributed under GFDL 1.1 or any later version
@c published by the Free Software Foundation.

@cindex sparse formats
@cindex sparse versions
The notion of sparse file, and the ways of handling it from the point
of view of @GNUTAR{} user have been described in detail in
@ref{sparse}.  This chapter describes the internal format @GNUTAR{}
uses to store such files.

The support for sparse files in @GNUTAR{} has a long history.  The
earliest version featuring this support that I was able to find was 1.09,
released in November, 1990.  The format introduced back then is called
@dfn{old GNU} sparse format and in spite of the fact that its design
contained many flaws, it was the only format @GNUTAR{} supported
until version 1.14 (May, 2004), which introduced initial support for
sparse archives in @acronym{PAX} archives (@pxref{posix}).  This
format was not free from design flows, either and it was subsequently
improved in versions 1.15.2 (November, 2005) and 1.15.92 (June,
2006).

In addition to GNU sparse format, @GNUTAR{} is able to read and
extract sparse files archived by @command{star}.

The following subsections describe each format in detail.

@menu
* Old GNU Format::
* PAX 0::                PAX Format, Versions 0.0 and 0.1
* PAX 1::                PAX Format, Version 1.0
@end menu

@node Old GNU Format
@appendixsubsec Old GNU Format

@cindex sparse formats, Old GNU
@cindex Old GNU sparse format
The format introduced some time around 1990 (v. 1.09).  It was
designed on top of standard @code{ustar} headers in such an
unfortunate way that some of its fields overwrote fields required by
POSIX.

An old GNU sparse header is designated by type @samp{S}
(@code{GNUTYPE_SPARSE}) and has the following layout:

@multitable @columnfractions 0.10 0.10 0.20 0.20 0.40
@headitem Offset @tab Size @tab Name   @tab Data type   @tab Contents
@item          0 @tab 345  @tab        @tab N/A         @tab Not used.
@item        345 @tab  12  @tab atime  @tab Number      @tab @code{atime} of the file.
@item        357 @tab  12  @tab ctime  @tab Number      @tab @code{ctime} of the file .
@item        369 @tab  12  @tab offset @tab Number      @tab For
multivolume archives: the offset of the start of this volume.
@item        381 @tab   4  @tab        @tab N/A         @tab Not used.
@item        385 @tab   1  @tab        @tab N/A         @tab Not used.
@item        386 @tab  96  @tab sp     @tab @code{sparse_header} @tab (4 entries) File map.
@item        482 @tab   1  @tab isextended @tab Bool        @tab @code{1} if an
extension sparse header follows, @code{0} otherwise.
@item        483 @tab  12  @tab realsize @tab Number      @tab Real size of the file.
@end multitable

Each of @code{sparse_header} object at offset 386 describes a single
data chunk. It has the following structure:

@multitable @columnfractions 0.10 0.10 0.20 0.60
@headitem Offset @tab Size @tab Data type   @tab Contents
@item          0 @tab   12 @tab Number      @tab Offset of the
beginning of the chunk.
@item         12 @tab   12 @tab Number      @tab Size of the chunk.
@end multitable

If the member contains more than four chunks, the @code{isextended}
field of the header has the value @code{1} and the main header is
followed by one or more @dfn{extension headers}.  Each such header has
the following structure:

@multitable @columnfractions 0.10 0.10 0.20 0.20 0.40
@headitem Offset @tab Size @tab Name   @tab Data type   @tab Contents
@item          0 @tab   21 @tab sp     @tab @code{sparse_header} @tab
(21 entires) File map.
@item        504 @tab    1 @tab isextended @tab Bool    @tab @code{1} if an
extension sparse header follows, or @code{0} otherwise.
@end multitable

A header with @code{isextended=0} ends the map.

@node PAX 0
@appendixsubsec PAX Format, Versions 0.0 and 0.1

@cindex sparse formats, v.0.0
There are two formats available in this branch.  The version @code{0.0}
is the initial version of sparse format used by @command{tar}
versions 1.14--1.15.1.  The sparse file map is kept in extended
(@code{x}) PAX header variables:

@table @code
@vrindex GNU.sparse.size, extended header variable
@item GNU.sparse.size
Real size of the stored file

@item GNU.sparse.numblocks
@vrindex GNU.sparse.numblocks, extended header variable
Number of blocks in the sparse map

@item GNU.sparse.offset
@vrindex GNU.sparse.offset, extended header variable
Offset of the data block

@item GNU.sparse.numbytes
@vrindex GNU.sparse.numbytes, extended header variable
Size of the data block
@end table

The latter two variables repeat for each data block, so the overall
structure is like this:

@smallexample
@group
GNU.sparse.size=@var{size}
GNU.sparse.numblocks=@var{numblocks}
repeat @var{numblocks} times
  GNU.sparse.offset=@var{offset}
  GNU.sparse.numbytes=@var{numbytes}
end repeat
@end group
@end smallexample

This format presented the following two problems:

@enumerate 1
@item
Whereas the POSIX specification allows a variable to appear multiple
times in a header, it requires that only the last occurrence be
meaningful.  Thus, multiple ocurrences of @code{GNU.sparse.offset} and
@code{GNU.sparse.numbytes} are conficting with the POSIX specs.

@item
Attempting to extract such archives using a third-party @command{tar}s
results in extraction of sparse files in @emph{compressed form}.  If
the @command{tar} implementation in question does not support POSIX
format, it will also extract a file containing extension header
attributes.  This file can be used to expand the file to its original
state.  However, posix-aware @command{tar}s will usually ignore the
unknown variables, which makes restoring the file more
difficult.  @xref{extracting sparse v.0.x, Extraction of sparse
members in v.0.0 format}, for the detailed description of how to
restore such members using non-GNU @command{tar}s.
@end enumerate

@cindex sparse formats, v.0.1
@GNUTAR{} 1.15.2 introduced sparse format version @code{0.1}, which
attempted to solve these problems.  As its predecessor, this format
stores sparse map in the extended POSIX header.  It retains
@code{GNU.sparse.size} and @code{GNU.sparse.numblocks} variables, but
instead of @code{GNU.sparse.offset}/@code{GNU.sparse.numbytes} pairs
it uses a single variable:

@table @code
@item GNU.sparse.map
@vrindex GNU.sparse.map, extended header variable
Map of non-null data chunks.  It is a string consisting of
comma-separated values "@var{offset},@var{size}[,@var{offset-1},@var{size-1}...]"
@end table

To address the 2nd problem, the @code{name} field in @code{ustar}
is replaced with a special name, constructed using the following pattern:

@smallexample
%d/GNUSparseFile.%p/%f
@end smallexample

@vrindex GNU.sparse.name, extended header variable
The real name of the sparse file is stored in the variable
@code{GNU.sparse.name}.  Thus, those @command{tar} implementations
that are not aware of GNU extensions will at least extract the files
into separate directories, giving the user a possibility to expand it
afterwards.  @xref{extracting sparse v.0.x, Extraction of sparse
members in v.0.1 format}, for the detailed description of how to
restore such members using non-GNU @command{tar}s.

The resulting @code{GNU.sparse.map} string can be @emph{very} long.
Although POSIX does not impose any limit on the length of a @code{x}
header variable, this possibly can confuse some tars.

@node PAX 1
@appendixsubsec PAX Format, Version 1.0

@cindex sparse formats, v.1.0
The version @code{1.0} of sparse format was introduced with @GNUTAR{}
1.15.92.  Its main objective was to make the resulting file
extractable with little effort even by non-posix aware @command{tar}
implementations.  Starting from this version, the extended header
preceding a sparse member always contains the following variables that
identify the format being used:

@table @code
@item GNU.sparse.major
@vrindex GNU.sparse.major, extended header variable
Major version

@item GNU.sparse.minor
@vrindex GNU.sparse.minor, extended header variable
Minor version
@end table

The @code{name} field in @code{ustar} header contains a special name,
constructed using the following pattern:

@smallexample
%d/GNUSparseFile.%p/%f
@end smallexample

@vrindex GNU.sparse.name, extended header variable, in v.1.0
@vrindex GNU.sparse.realsize, extended header variable
The real name of the sparse file is stored in the variable
@code{GNU.sparse.name}.  The real size of the file is stored in the
variable @code{GNU.sparse.realsize}.

The sparse map itself is stored in the file data block, preceding the actual
file data.  It consists of a series of octal numbers of arbitrary length, delimited
by newlines. The map is padded with nulls to the nearest block boundary.

The first number gives the number of entries in the map. Following are map entries,
each one consisting of two numbers giving the offset and size of the
data block it describes.

The format is designed in such a way that non-posix aware tars and tars not
supporting @code{GNU.sparse.*} keywords will extract each sparse file
in its condensed form with the file map prepended and will place it
into a separate directory.  Then, using a simple program it would be
possible to expand the file to its original form even without @GNUTAR{}.
@xref{Sparse Recovery}, for the detailed information on how to extract
sparse members without @GNUTAR{}.