src/site/xdoc/tar.xml - commons-compress - Git at Google

 <?xml version="1.0"?>
 <!--

    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

 -->
 <document>
   <properties>
     <title>Commons Compress TAR package</title>
     <author email="dev@commons.apache.org">Commons Documentation Team</author>
   </properties>
   <body>
     <section name="The TAR package">

       <p>In addition to the information stored
       in <code>ArchiveEntry</code> a <code>TarArchiveEntry</code>
       stores various attributes including information about the
       original owner and permissions.</p>

       <p>There are several different tar formats and the TAR package
       of Compress 1.4 mostly only provides the common functionality
       of the existing variants.</p>

       <p>The original format (often called "ustar") didn't support
       file names longer than 100 characters or bigger than 8 GiB and
       the tar package will by default fail if you try to write an
       entry that goes beyond those limits.</p>

       <p>The tar package does not support the full POSIX tar standard
       nor more modern GNU extension of said standard.</p>

       <subsection name="Long File Names">

         <p>The <code>longFileMode</code> option of
         <code>TarArchiveOutputStream</code> controls how files with
         names longer than 100 characters are handled.  The possible
         choices are:</p>

         <ul>
           <li><code>LONGFILE_ERROR</code>: throw an exception if such a
           file is added.  This is the default.</li>
           <li><code>LONGFILE_TRUNCATE</code>: truncate such names.</li>
           <li><code>LONGFILE_GNU</code>: use a GNU tar variant now
           refered to as "oldgnu" of storing such names.  If you choose
           the GNU tar option, the archive can not be extracted using
           many other tar implementations like the ones of OpenBSD,
           Solaris or MacOS X.</li>
           <li><code>LONGFILE_POSIX</code>: use a PAX <a
           href="http://pubs.opengroup.org/onlinepubs/009695399/utilities/pax.html#tag_04_100_13_03">extended
           header</a> as defined by POSIX 1003.1.  Most modern tar
           implementations are able to extract such archives. <em>since
           Commons Compress 1.4</em></li>
         </ul>

         <p><code>TarArchiveInputStream</code> will recognize the GNU
         tar as well as the POSIX extensions (starting with Commons
         Compress 1.2) for long file names and reads the longer names
         transparently.</p>
       </subsection>

       <subsection name="Big Numeric Values">

         <p>The <code>bigNumberMode</code> option of
         <code>TarArchiveOutputStream</code> controls how files larger
         than 8GiB or with other big numeric values that can't be
         encoded in traditional header fields are handled.  The
         possible choices are:</p>

         <ul>
           <li><code>BIGNUMBER_ERROR</code>: throw an exception if such an
           entry is added.  This is the default.</li>
           <li><code>BIGNUMBER_STAR</code>: use a variant first
           introduced by J&#xf6;rg Schilling's <a
           href="http://developer.berlios.de/projects/star">star</a>
           and later adopted by GNU and BSD tar.  This method is not
           supported by all implementations.</li>
           <li><code>BIGNUMBER_POSIX</code>: use a PAX <a
           href="http://pubs.opengroup.org/onlinepubs/009695399/utilities/pax.html#tag_04_100_13_03">extended
           header</a> as defined by POSIX 1003.1.  Most modern tar
           implementations are able to extract such archives.</li>
         </ul>

         <p>Starting with Commons Compress 1.4
         <code>TarArchiveInputStream</code> will recognize the star as
         well as the POSIX extensions for big numeric values and reads them
         transparently.</p>
       </subsection>

       <subsection name="File Name Encoding">
         <p>The original ustar format only supports 7-Bit ASCII file
         names, later implementations use the platform's default
         encoding to encode file names.  The POSIX standard recommends
         using PAX extension headers for non-ASCII file names
         instead.</p>

         <p>Commons Compress 1.1 to 1.3 assumed file names would be
         encoded using ISO-8859-1.  Starting with Commons Compress 1.4
         you can specify the encoding to expect (to use when writing)
         as a parameter to <code>TarArchiveInputStream</code>
         (<code>TarArchiveOutputStream</code>), it now defaults to the
         platform's default encoding.</p>

         <p>Since Commons Compress 1.4 another optional parameter -
         <code>addPaxHeadersForNonAsciiNames</code> - of
         <code>TarArchiveOutputStream</code> controls whether PAX
         extension headers will be written for non-ASCII file names.
         By default they will not be written to preserve space.
         <code>TarArchiveInputStream</code> will read them
         transparently if present.</p>
       </subsection>

       <subsection name="Sparse files">

         <p><code>TarArchiveInputStream</code> will recognize sparse
         file entries stored using the "oldgnu" format
         (<code>-&#x2d;sparse-version=0.0</code> in GNU tar) but is not
         able to extract them correctly.  <a href="#Unsupported
         Features"><code>canReadEntryData</code></a> will return false
         on such entries.  The other variants of sparse files can
         currently not be detected at all.</p>
       </subsection>

       <subsection name="Consuming Archives Completely">

         <p>The end of a tar archive is signalled by two consecutive
         records of all zeros.  Unfortunately not all tar
         implementations adhere to this and some only write one record
         to end the archive.  Commons Compress will always write two
         records but stop reading an archive as soon as finds one
         record of all zeros.</p>

         <p>Prior to version 1.5 this could leave the second EOF record
         inside the stream when <code>getNextEntry</code> or
         <code>getNextTarEntry</code> returned <code>null</code>
         Starting with version 1.5 <code>TarArchiveInputStream</code>
         will try to read a second record as well if present,
         effectively consuming the archive completely.</p>

       </subsection>

     </section>
   </body>
 </document>
	<?xml version="1.0"?>
	<!--

	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.

	-->
	<document>
	<properties>
	<title>Commons Compress TAR package</title>
	<author email="dev@commons.apache.org">Commons Documentation Team</author>
	</properties>
	<body>
	<section name="The TAR package">

	<p>In addition to the information stored
	in <code>ArchiveEntry</code> a <code>TarArchiveEntry</code>
	stores various attributes including information about the
	original owner and permissions.</p>

	<p>There are several different tar formats and the TAR package
	of Compress 1.4 mostly only provides the common functionality
	of the existing variants.</p>

	<p>The original format (often called "ustar") didn't support
	file names longer than 100 characters or bigger than 8 GiB and
	the tar package will by default fail if you try to write an
	entry that goes beyond those limits.</p>

	<p>The tar package does not support the full POSIX tar standard
	nor more modern GNU extension of said standard.</p>

	<subsection name="Long File Names">

	<p>The <code>longFileMode</code> option of
	<code>TarArchiveOutputStream</code> controls how files with
	names longer than 100 characters are handled. The possible
	choices are:</p>

	<ul>
	<li><code>LONGFILE_ERROR</code>: throw an exception if such a
	file is added. This is the default.</li>
	<li><code>LONGFILE_TRUNCATE</code>: truncate such names.</li>
	<li><code>LONGFILE_GNU</code>: use a GNU tar variant now
	refered to as "oldgnu" of storing such names. If you choose
	the GNU tar option, the archive can not be extracted using
	many other tar implementations like the ones of OpenBSD,
	Solaris or MacOS X.</li>
	<li><code>LONGFILE_POSIX</code>: use a PAX <a
	href="http://pubs.opengroup.org/onlinepubs/009695399/utilities/pax.html#tag_04_100_13_03">extended
	header</a> as defined by POSIX 1003.1. Most modern tar
	implementations are able to extract such archives. <em>since
	Commons Compress 1.4</em></li>
	</ul>

	<p><code>TarArchiveInputStream</code> will recognize the GNU
	tar as well as the POSIX extensions (starting with Commons
	Compress 1.2) for long file names and reads the longer names
	transparently.</p>
	</subsection>

	<subsection name="Big Numeric Values">

	<p>The <code>bigNumberMode</code> option of
	<code>TarArchiveOutputStream</code> controls how files larger
	than 8GiB or with other big numeric values that can't be
	encoded in traditional header fields are handled. The
	possible choices are:</p>

	<ul>
	<li><code>BIGNUMBER_ERROR</code>: throw an exception if such an
	entry is added. This is the default.</li>
	<li><code>BIGNUMBER_STAR</code>: use a variant first
	introduced by Jörg Schilling's <a
	href="http://developer.berlios.de/projects/star">star</a>
	and later adopted by GNU and BSD tar. This method is not
	supported by all implementations.</li>
	<li><code>BIGNUMBER_POSIX</code>: use a PAX <a
	href="http://pubs.opengroup.org/onlinepubs/009695399/utilities/pax.html#tag_04_100_13_03">extended
	header</a> as defined by POSIX 1003.1. Most modern tar
	implementations are able to extract such archives.</li>
	</ul>

	<p>Starting with Commons Compress 1.4
	<code>TarArchiveInputStream</code> will recognize the star as
	well as the POSIX extensions for big numeric values and reads them
	transparently.</p>
	</subsection>

	<subsection name="File Name Encoding">
	<p>The original ustar format only supports 7-Bit ASCII file
	names, later implementations use the platform's default
	encoding to encode file names. The POSIX standard recommends
	using PAX extension headers for non-ASCII file names
	instead.</p>

	<p>Commons Compress 1.1 to 1.3 assumed file names would be
	encoded using ISO-8859-1. Starting with Commons Compress 1.4
	you can specify the encoding to expect (to use when writing)
	as a parameter to <code>TarArchiveInputStream</code>
	(<code>TarArchiveOutputStream</code>), it now defaults to the
	platform's default encoding.</p>

	<p>Since Commons Compress 1.4 another optional parameter -
	<code>addPaxHeadersForNonAsciiNames</code> - of
	<code>TarArchiveOutputStream</code> controls whether PAX
	extension headers will be written for non-ASCII file names.
	By default they will not be written to preserve space.
	<code>TarArchiveInputStream</code> will read them
	transparently if present.</p>
	</subsection>

	<subsection name="Sparse files">

	<p><code>TarArchiveInputStream</code> will recognize sparse
	file entries stored using the "oldgnu" format
	(<code>--sparse-version=0.0</code> in GNU tar) but is not
	able to extract them correctly. <a href="#Unsupported
	Features"><code>canReadEntryData</code></a> will return false
	on such entries. The other variants of sparse files can
	currently not be detected at all.</p>
	</subsection>

	<subsection name="Consuming Archives Completely">

	<p>The end of a tar archive is signalled by two consecutive
	records of all zeros. Unfortunately not all tar
	implementations adhere to this and some only write one record
	to end the archive. Commons Compress will always write two
	records but stop reading an archive as soon as finds one
	record of all zeros.</p>

	<p>Prior to version 1.5 this could leave the second EOF record
	inside the stream when <code>getNextEntry</code> or
	<code>getNextTarEntry</code> returned <code>null</code>
	Starting with version 1.5 <code>TarArchiveInputStream</code>
	will try to read a second record as well if present,
	effectively consuming the archive completely.</p>

	</subsection>

	</section>
	</body>
	</document>