From 55abc110f57e77109f687bd62347fc2ce5ec0c5b Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Mon, 26 Jun 2006 14:42:18 +0000 Subject: [PATCH] Add cross-references --- doc/sparse.texi | 31 ++++++++++++++++++++++++------- doc/tar.texi | 34 +++++++++++++++------------------- 2 files changed, 39 insertions(+), 26 deletions(-) diff --git a/doc/sparse.texi b/doc/sparse.texi index 7b9145d..1194357 100644 --- a/doc/sparse.texi +++ b/doc/sparse.texi @@ -3,6 +3,8 @@ @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{} @@ -33,6 +35,8 @@ The following subsections describe each format in detail. @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 @@ -83,24 +87,28 @@ A header with @code{isextended=0} ends the map. @node PAX 0 @appendixsubsec PAX Format, Versions 0.0 and 0.1 -@UNREVISED{} +@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 @@ -134,10 +142,13 @@ 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 much more -difficult@FIXME-xref{how to extract sparse file using third-party @command{tar}s}. +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 @@ -147,6 +158,7 @@ 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 @@ -158,6 +170,7 @@ is replaced with a special name, constructed using the following pattern: %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 @@ -171,8 +184,8 @@ header variable, this possibly can confuse some tars. @node PAX 1 @appendixsubsec PAX Format, Version 1.0 -@UNREVISED{} +@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} @@ -182,9 +195,11 @@ 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 @@ -195,6 +210,8 @@ constructed using the following pattern: %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}. @@ -211,7 +228,7 @@ 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 GNU tar. -@FIXME-xref{how to extract sparse file using third-party -@command{tar}s}. @FIXME{Write the program and give its URL here}. +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{}. diff --git a/doc/tar.texi b/doc/tar.texi index ac5f717..18176f2 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -13,9 +13,9 @@ @c Maintenance notes: @c 1. Pay attention to @FIXME{}s and @UNREVISED{}s @c 2. Before creating final variant: -@c 1.1. Run `make check-options' to make sure all options are properly +@c 2.1. Run `make check-options' to make sure all options are properly @c documented; -@c 2.1. Run `make master-menu' (see comment before the master menu). +@c 2.2. Run `make master-menu' (see comment before the master menu). @include rendition.texi @include value.texi @@ -526,7 +526,7 @@ pipes). @command{tar} may even access remote devices or files (as archives). You can use @command{tar} archives in many ways. We want to stress a few of them: storage, backup, and transportation. -@FIXME{the following table entries need a bit of work..} +@FIXME{the following table entries need a bit of work.} @table @asis @item Storage Often, @command{tar} archives are used to store related files for @@ -8573,6 +8573,7 @@ describe the required procedures in detail. @node Split Recovery @subsubsection Extracting Members Split Between Volumes +@cindex Mutli-volume archives, extracting using non-GNU tars If a member is split between several volumes of an old GNU format archive most third party @command{tar} implementation will fail to extract it. To extract it, use @command{tarcat} program (@pxref{Tarcat}). @@ -8587,6 +8588,7 @@ extract them using a third-party @command{tar}: $ @kbd{tarcat vol-1.tar vol-2.tar vol-3.tar | tar xf -} @end smallexample +@cindex Mutli-volume archives in PAX format, extracting using non-GNU tars You could use this approach for many (although not all) PAX format archives as well. However, extracting split members from a PAX archive is a much easier task, because PAX volumes are constructed in @@ -8678,6 +8680,7 @@ members. Read further to learn more about them. @node Sparse Recovery @subsubsection Extracting Sparse Members +@cindex sparse files, extracting with non-GNU tars Any @command{tar} implementation will be able to extract sparse members from a PAX archive. However, the extracted files will be @dfn{condensed}, i.e. any zero blocks will be removed from them. When we restore such @@ -8685,11 +8688,13 @@ a condensed file to its original form, by adding zero bloks (or @dfn{holes}) back to their original locations, we call this process @dfn{expanding} a compressed sparse file. +@pindex xsparse To expand a file, you will need a simple auxiliary program called @command{xsparse}. It is available in source form from @uref{http://www.gnu.org/@/software/@/tar/@/utils/@/xsparse.html, @GNUTAR{} home page}. +@cindex sparse files v.1.0, extracting with non-GNU tars Let's begin with archive members in @dfn{sparse format version 1.0}@footnote{@xref{PAX 1}.}, which are the easiest to expand. The condensed file will contain both file map and file data, so no @@ -8792,6 +8797,9 @@ Done @end group @end smallexample +@anchor{extracting sparse v.0.x} +@cindex sparse files v.0.1, extracting with non-GNU tars +@cindex sparse files v.0.0, extracting with non-GNU tars An @dfn{extended header} is a special @command{tar} archive header that precedes an archive member and contains a set of @dfn{variables}, describing the member properties that cannot be @@ -10165,22 +10173,10 @@ added later. To label subsequent volumes, specify @option{--label=@var{archive-label}} again in conjunction with the @option{--append}, @option{--update} or @option{--concatenate} operation. -@FIXME{This is no longer true: Multivolume archives in @samp{POSIX} -format can be extracted using any posix-compliant tar -implementation. The split members can then be recreated from parts -using a simple shell script. Provide more information about it:} -Beware that there is @emph{no} real standard about the proper way, for -a @command{tar} archive, to span volume boundaries. If you have a -multi-volume created by some vendor's @command{tar}, there is almost -no chance you could read all the volumes with @GNUTAR{}. -The converse is also true: you may not expect -multi-volume archives created by @GNUTAR{} to be -fully recovered by vendor's @command{tar}. Since there is little -chance that, in mixed system configurations, some vendor's -@command{tar} will work on another vendor's machine, and there is a -great chance that @GNUTAR{} will work on most of -them, your best bet is to install @GNUTAR{} on all -machines between which you know exchange of files is possible. +Notice that multi-volume support is a GNU extension and the archives +created in this mode should be read only using @GNUTAR{}. If you +absolutely have to process such archives using a third-party @command{tar} +implementation, read @ref{Split Recovery}. @node Tape Files @subsection Tape Files -- 2.45.2