X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FGitalist.git;a=blobdiff_plain;f=local-lib5%2Fman%2Fman3%2FArchive%3A%3ATar.3pm;fp=local-lib5%2Fman%2Fman3%2FArchive%3A%3ATar.3pm;h=4cfcc35a2d5656193013f9644b7f76e33ddca397;hp=0000000000000000000000000000000000000000;hb=3fea05b9fbf95091f4522528b9980a33e0235603;hpb=af746827daa7a8feccee889e1d12ebc74cc9201e

diff --git a/local-lib5/man/man3/Archive::Tar.3pm b/local-lib5/man/man3/Archive::Tar.3pm
new file mode 100644
index 0000000..4cfcc35
--- /dev/null
+++ b/local-lib5/man/man3/Archive::Tar.3pm
@@ -0,0 +1,995 @@
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  | will give a
+.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
+.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
+.\" expand to `' in nroff, nothing in troff, for use with C<>.
+.tr \(*W-|\(bv\*(Tr
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.\"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "Archive::Tar 3"
+.TH Archive::Tar 3 "2009-09-10" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+Archive::Tar \- module for manipulations of tar archives
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 2
+\&    use Archive::Tar;
+\&    my $tar = Archive::Tar\->new;
+.Ve
+.PP
+.Vb 2
+\&    $tar\->read('origin.tgz');
+\&    $tar\->extract();
+.Ve
+.PP
+.Vb 2
+\&    $tar\->add_files('file/foo.pl', 'docs/README');
+\&    $tar\->add_data('file/baz.txt', 'This is the contents now');
+.Ve
+.PP
+.Vb 1
+\&    $tar\->rename('oldname', 'new/file/name');
+.Ve
+.PP
+.Vb 3
+\&    $tar\->write('files.tar');                   # plain tar
+\&    $tar\->write('files.tgz', COMPRESS_GZIP);    # gzip compressed
+\&    $tar\->write('files.tbz', COMPRESS_BZIP);    # bzip2 compressed
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+Archive::Tar provides an object oriented mechanism for handling tar
+files.  It provides class methods for quick and easy files handling
+while also allowing for the creation of tar file objects for custom
+manipulation.  If you have the IO::Zlib module installed,
+Archive::Tar will also support compressed or gzipped tar files.
+.PP
+An object of class Archive::Tar represents a .tar(.gz) archive full
+of files and things.
+.SH "Object Methods"
+.IX Header "Object Methods"
+.ie n .Sh "Archive::Tar\->new( [$file, $compressed] )"
+.el .Sh "Archive::Tar\->new( [$file, \f(CW$compressed\fP] )"
+.IX Subsection "Archive::Tar->new( [$file, $compressed] )"
+Returns a new Tar object. If given any arguments, \f(CW\*(C`new()\*(C'\fR calls the
+\&\f(CW\*(C`read()\*(C'\fR method automatically, passing on the arguments provided to
+the \f(CW\*(C`read()\*(C'\fR method.
+.PP
+If \f(CW\*(C`new()\*(C'\fR is invoked with arguments and the \f(CW\*(C`read()\*(C'\fR method fails
+for any reason, \f(CW\*(C`new()\*(C'\fR returns undef.
+.ie n .Sh "$tar\->read ( $filename|$handle, [$compressed, {opt => 'val'}] )"
+.el .Sh "$tar\->read ( \f(CW$filename\fP|$handle, [$compressed, {opt => 'val'}] )"
+.IX Subsection "$tar->read ( $filename|$handle, [$compressed, {opt => 'val'}] )"
+Read the given tar file into memory.
+The first argument can either be the name of a file or a reference to
+an already open filehandle (or an IO::Zlib object if it's compressed)
+.PP
+The \f(CW\*(C`read\*(C'\fR will \fIreplace\fR any previous content in \f(CW$tar\fR!
+.PP
+The second argument may be considered optional, but remains for
+backwards compatibility. Archive::Tar now looks at the file
+magic to determine what class should be used to open the file
+and will transparently Do The Right Thing.
+.PP
+Archive::Tar will warn if you try to pass a bzip2 compressed file and the
+IO::Zlib / IO::Uncompress::Bunzip2 modules are not available and simply return.
+.PP
+Note that you can currently \fBnot\fR pass a \f(CW\*(C`gzip\*(C'\fR compressed
+filehandle, which is not opened with \f(CW\*(C`IO::Zlib\*(C'\fR, a \f(CW\*(C`bzip2\*(C'\fR compressed
+filehandle, which is not opened with \f(CW\*(C`IO::Uncompress::Bunzip2\*(C'\fR, nor a string
+containing the full archive information (either compressed or
+uncompressed). These are worth while features, but not currently
+implemented. See the \f(CW\*(C`TODO\*(C'\fR section.
+.PP
+The third argument can be a hash reference with options. Note that
+all options are case\-sensitive.
+.IP "limit" 4
+.IX Item "limit"
+Do not read more than \f(CW\*(C`limit\*(C'\fR files. This is useful if you have
+very big archives, and are only interested in the first few files.
+.IP "filter" 4
+.IX Item "filter"
+Can be set to a regular expression.  Only files with names that match
+the expression will be read.
+.IP "extract" 4
+.IX Item "extract"
+If set to true, immediately extract entries when reading them. This
+gives you the same memory break as the \f(CW\*(C`extract_archive\*(C'\fR function.
+Note however that entries will not be read into memory, but written
+straight to disk. This means no \f(CW\*(C`Archive::Tar::File\*(C'\fR objects are
+created for you to inspect.
+.PP
+All files are stored internally as \f(CW\*(C`Archive::Tar::File\*(C'\fR objects.
+Please consult the Archive::Tar::File documentation for details.
+.PP
+Returns the number of files read in scalar context, and a list of
+\&\f(CW\*(C`Archive::Tar::File\*(C'\fR objects in list context.
+.ie n .Sh "$tar\->contains_file( $filename )"
+.el .Sh "$tar\->contains_file( \f(CW$filename\fP )"
+.IX Subsection "$tar->contains_file( $filename )"
+Check if the archive contains a certain file.
+It will return true if the file is in the archive, false otherwise.
+.PP
+Note however, that this function does an exact match using \f(CW\*(C`eq\*(C'\fR
+on the full path. So it cannot compensate for case-insensitive file\-
+systems or compare 2 paths to see if they would point to the same
+underlying file.
+.Sh "$tar\->extract( [@filenames] )"
+.IX Subsection "$tar->extract( [@filenames] )"
+Write files whose names are equivalent to any of the names in
+\&\f(CW@filenames\fR to disk, creating subdirectories as necessary. This
+might not work too well under \s-1VMS\s0.
+Under MacPerl, the file's modification time will be converted to the
+MacOS zero of time, and appropriate conversions will be done to the
+path.  However, the length of each element of the path is not
+inspected to see whether it's longer than MacOS currently allows (32
+characters).
+.PP
+If \f(CW\*(C`extract\*(C'\fR is called without a list of file names, the entire
+contents of the archive are extracted.
+.PP
+Returns a list of filenames extracted.
+.ie n .Sh "$tar\->extract_file( $file, [$extract_path] )"
+.el .Sh "$tar\->extract_file( \f(CW$file\fP, [$extract_path] )"
+.IX Subsection "$tar->extract_file( $file, [$extract_path] )"
+Write an entry, whose name is equivalent to the file name provided to
+disk. Optionally takes a second parameter, which is the full native
+path (including filename) the entry will be written to.
+.PP
+For example:
+.PP
+.Vb 1
+\&    $tar\->extract_file( 'name/in/archive', 'name/i/want/to/give/it' );
+.Ve
+.PP
+.Vb 1
+\&    $tar\->extract_file( $at_file_object,   'name/i/want/to/give/it' );
+.Ve
+.PP
+Returns true on success, false on failure.
+.Sh "$tar\->list_files( [\e@properties] )"
+.IX Subsection "$tar->list_files( [@properties] )"
+Returns a list of the names of all the files in the archive.
+.PP
+If \f(CW\*(C`list_files()\*(C'\fR is passed an array reference as its first argument
+it returns a list of hash references containing the requested
+properties of each file.  The following list of properties is
+supported: name, size, mtime (last modified date), mode, uid, gid,
+linkname, uname, gname, devmajor, devminor, prefix.
+.PP
+Passing an array reference containing only one element, 'name', is
+special cased to return a list of names rather than a list of hash
+references, making it equivalent to calling \f(CW\*(C`list_files\*(C'\fR without
+arguments.
+.Sh "$tar\->get_files( [@filenames] )"
+.IX Subsection "$tar->get_files( [@filenames] )"
+Returns the \f(CW\*(C`Archive::Tar::File\*(C'\fR objects matching the filenames
+provided. If no filename list was passed, all \f(CW\*(C`Archive::Tar::File\*(C'\fR
+objects in the current Tar object are returned.
+.PP
+Please refer to the \f(CW\*(C`Archive::Tar::File\*(C'\fR documentation on how to
+handle these objects.
+.ie n .Sh "$tar\->get_content( $file )"
+.el .Sh "$tar\->get_content( \f(CW$file\fP )"
+.IX Subsection "$tar->get_content( $file )"
+Return the content of the named file.
+.ie n .Sh "$tar\->replace_content( $file\fP, \f(CW$content )"
+.el .Sh "$tar\->replace_content( \f(CW$file\fP, \f(CW$content\fP )"
+.IX Subsection "$tar->replace_content( $file, $content )"
+Make the string \f(CW$content\fR be the content for the file named \f(CW$file\fR.
+.ie n .Sh "$tar\->rename( $file\fP, \f(CW$new_name )"
+.el .Sh "$tar\->rename( \f(CW$file\fP, \f(CW$new_name\fP )"
+.IX Subsection "$tar->rename( $file, $new_name )"
+Rename the file of the in-memory archive to \f(CW$new_name\fR.
+.PP
+Note that you must specify a Unix path for \f(CW$new_name\fR, since per tar
+standard, all files in the archive must be Unix paths.
+.PP
+Returns true on success and false on failure.
+.Sh "$tar\->remove (@filenamelist)"
+.IX Subsection "$tar->remove (@filenamelist)"
+Removes any entries with names matching any of the given filenames
+from the in-memory archive. Returns a list of \f(CW\*(C`Archive::Tar::File\*(C'\fR
+objects that remain.
+.Sh "$tar\->clear"
+.IX Subsection "$tar->clear"
+\&\f(CW\*(C`clear\*(C'\fR clears the current in-memory archive. This effectively gives
+you a 'blank' object, ready to be filled again. Note that \f(CW\*(C`clear\*(C'\fR
+only has effect on the object, not the underlying tarfile.
+.ie n .Sh "$tar\->write ( [$file, $compressed\fP, \f(CW$prefix] )"
+.el .Sh "$tar\->write ( [$file, \f(CW$compressed\fP, \f(CW$prefix\fP] )"
+.IX Subsection "$tar->write ( [$file, $compressed, $prefix] )"
+Write the in-memory archive to disk.  The first argument can either
+be the name of a file or a reference to an already open filehandle (a
+\&\s-1GLOB\s0 reference).
+.PP
+The second argument is used to indicate compression. You can either
+compress using \f(CW\*(C`gzip\*(C'\fR or \f(CW\*(C`bzip2\*(C'\fR. If you pass a digit, it's assumed
+to be the \f(CW\*(C`gzip\*(C'\fR compression level (between 1 and 9), but the use of
+constants is prefered:
+.PP
+.Vb 2
+\&  # write a gzip compressed file
+\&  $tar\->write( 'out.tgz', COMPRESS_GZIP );
+.Ve
+.PP
+.Vb 2
+\&  # write a bzip compressed file
+\&  $tar\->write( 'out.tbz', COMPRESS_BZIP );
+.Ve
+.PP
+Note that when you pass in a filehandle, the compression argument
+is ignored, as all files are printed verbatim to your filehandle.
+If you wish to enable compression with filehandles, use an
+\&\f(CW\*(C`IO::Zlib\*(C'\fR or \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR filehandle instead.
+.PP
+The third argument is an optional prefix. All files will be tucked
+away in the directory you specify as prefix. So if you have files
+\&'a' and 'b' in your archive, and you specify 'foo' as prefix, they
+will be written to the archive as 'foo/a' and 'foo/b'.
+.PP
+If no arguments are given, \f(CW\*(C`write\*(C'\fR returns the entire formatted
+archive as a string, which could be useful if you'd like to stuff the
+archive into a socket or a pipe to gzip or something.
+.ie n .Sh "$tar\->add_files( @filenamelist )"
+.el .Sh "$tar\->add_files( \f(CW@filenamelist\fP )"
+.IX Subsection "$tar->add_files( @filenamelist )"
+Takes a list of filenames and adds them to the in-memory archive.
+.PP
+The path to the file is automatically converted to a Unix like
+equivalent for use in the archive, and, if on MacOS, the file's
+modification time is converted from the MacOS epoch to the Unix epoch.
+So tar archives created on MacOS with \fBArchive::Tar\fR can be read
+both with \fItar\fR on Unix and applications like \fIsuntar\fR or
+\&\fIStuffit Expander\fR on MacOS.
+.PP
+Be aware that the file's type/creator and resource fork will be lost,
+which is usually what you want in cross-platform archives.
+.PP
+Instead of a filename, you can also pass it an existing \f(CW\*(C`Archive::Tar::File\*(C'\fR
+object from, for example, another archive. The object will be clone, and
+effectively be a copy of the original, not an alias.
+.PP
+Returns a list of \f(CW\*(C`Archive::Tar::File\*(C'\fR objects that were just added.
+.ie n .Sh "$tar\->add_data ( $filename\fP, \f(CW$data, [$opthashref] )"
+.el .Sh "$tar\->add_data ( \f(CW$filename\fP, \f(CW$data\fP, [$opthashref] )"
+.IX Subsection "$tar->add_data ( $filename, $data, [$opthashref] )"
+Takes a filename, a scalar full of data and optionally a reference to
+a hash with specific options.
+.PP
+Will add a file to the in-memory archive, with name \f(CW$filename\fR and
+content \f(CW$data\fR. Specific properties can be set using \f(CW$opthashref\fR.
+The following list of properties is supported: name, size, mtime
+(last modified date), mode, uid, gid, linkname, uname, gname,
+devmajor, devminor, prefix, type.  (On MacOS, the file's path and
+modification times are converted to Unix equivalents.)
+.PP
+Valid values for the file type are the following constants defined in
+Archive::Tar::Constants:
+.IP "\s-1FILE\s0" 4
+.IX Item "FILE"
+Regular file.
+.IP "\s-1HARDLINK\s0" 4
+.IX Item "HARDLINK"
+.PD 0
+.IP "\s-1SYMLINK\s0" 4
+.IX Item "SYMLINK"
+.PD
+Hard and symbolic (\*(L"soft\*(R") links; linkname should specify target.
+.IP "\s-1CHARDEV\s0" 4
+.IX Item "CHARDEV"
+.PD 0
+.IP "\s-1BLOCKDEV\s0" 4
+.IX Item "BLOCKDEV"
+.PD
+Character and block devices. devmajor and devminor should specify the major
+and minor device numbers.
+.IP "\s-1DIR\s0" 4
+.IX Item "DIR"
+Directory.
+.IP "\s-1FIFO\s0" 4
+.IX Item "FIFO"
+\&\s-1FIFO\s0 (named pipe).
+.IP "\s-1SOCKET\s0" 4
+.IX Item "SOCKET"
+Socket.
+.PP
+Returns the \f(CW\*(C`Archive::Tar::File\*(C'\fR object that was just added, or
+\&\f(CW\*(C`undef\*(C'\fR on failure.
+.Sh "$tar\->error( [$BOOL] )"
+.IX Subsection "$tar->error( [$BOOL] )"
+Returns the current errorstring (usually, the last error reported).
+If a true value was specified, it will give the \f(CW\*(C`Carp::longmess\*(C'\fR
+equivalent of the error, in effect giving you a stacktrace.
+.PP
+For backwards compatibility, this error is also available as
+\&\f(CW$Archive::Tar::error\fR although it is much recommended you use the
+method call instead.
+.ie n .Sh "$tar\->setcwd( $cwd );"
+.el .Sh "$tar\->setcwd( \f(CW$cwd\fP );"
+.IX Subsection "$tar->setcwd( $cwd );"
+\&\f(CW\*(C`Archive::Tar\*(C'\fR needs to know the current directory, and it will run
+\&\f(CW\*(C`Cwd::cwd()\*(C'\fR \fIevery\fR time it extracts a \fIrelative\fR entry from the
+tarfile and saves it in the file system. (As of version 1.30, however,
+\&\f(CW\*(C`Archive::Tar\*(C'\fR will use the speed optimization described below
+automatically, so it's only relevant if you're using \f(CW\*(C`extract_file()\*(C'\fR).
+.PP
+Since \f(CW\*(C`Archive::Tar\*(C'\fR doesn't change the current directory internally
+while it is extracting the items in a tarball, all calls to \f(CW\*(C`Cwd::cwd()\*(C'\fR
+can be avoided if we can guarantee that the current directory doesn't
+get changed externally.
+.PP
+To use this performance boost, set the current directory via
+.PP
+.Vb 2
+\&    use Cwd;
+\&    $tar\->setcwd( cwd() );
+.Ve
+.PP
+once before calling a function like \f(CW\*(C`extract_file\*(C'\fR and
+\&\f(CW\*(C`Archive::Tar\*(C'\fR will use the current directory setting from then on
+and won't call \f(CW\*(C`Cwd::cwd()\*(C'\fR internally.
+.PP
+To switch back to the default behaviour, use
+.PP
+.Vb 1
+\&    $tar\->setcwd( undef );
+.Ve
+.PP
+and \f(CW\*(C`Archive::Tar\*(C'\fR will call \f(CW\*(C`Cwd::cwd()\*(C'\fR internally again.
+.PP
+If you're using \f(CW\*(C`Archive::Tar\*(C'\fR's \f(CW\*(C`exract()\*(C'\fR method, \f(CW\*(C`setcwd()\*(C'\fR will
+be called for you.
+.SH "Class Methods"
+.IX Header "Class Methods"
+.ie n .Sh "Archive::Tar\->create_archive($file, $compressed\fP, \f(CW@filelist)"
+.el .Sh "Archive::Tar\->create_archive($file, \f(CW$compressed\fP, \f(CW@filelist\fP)"
+.IX Subsection "Archive::Tar->create_archive($file, $compressed, @filelist)"
+Creates a tar file from the list of files provided.  The first
+argument can either be the name of the tar file to create or a
+reference to an open file handle (e.g. a \s-1GLOB\s0 reference).
+.PP
+The second argument is used to indicate compression. You can either
+compress using \f(CW\*(C`gzip\*(C'\fR or \f(CW\*(C`bzip2\*(C'\fR. If you pass a digit, it's assumed
+to be the \f(CW\*(C`gzip\*(C'\fR compression level (between 1 and 9), but the use of
+constants is prefered:
+.PP
+.Vb 2
+\&  # write a gzip compressed file
+\&  Archive::Tar\->create_archive( 'out.tgz', COMPRESS_GZIP, @filelist );
+.Ve
+.PP
+.Vb 2
+\&  # write a bzip compressed file
+\&  Archive::Tar\->create_archive( 'out.tbz', COMPRESS_BZIP, @filelist );
+.Ve
+.PP
+Note that when you pass in a filehandle, the compression argument
+is ignored, as all files are printed verbatim to your filehandle.
+If you wish to enable compression with filehandles, use an
+\&\f(CW\*(C`IO::Zlib\*(C'\fR or \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR filehandle instead.
+.PP
+The remaining arguments list the files to be included in the tar file.
+These files must all exist. Any files which don't exist or can't be
+read are silently ignored.
+.PP
+If the archive creation fails for any reason, \f(CW\*(C`create_archive\*(C'\fR will
+return false. Please use the \f(CW\*(C`error\*(C'\fR method to find the cause of the
+failure.
+.PP
+Note that this method does not write \f(CW\*(C`on the fly\*(C'\fR as it were; it
+still reads all the files into memory before writing out the archive.
+Consult the \s-1FAQ\s0 below if this is a problem.
+.ie n .Sh "Archive::Tar\->iter( $filename\fP, [ \f(CW$compressed\fP, {opt => \f(CW$val} ] )"
+.el .Sh "Archive::Tar\->iter( \f(CW$filename\fP, [ \f(CW$compressed\fP, {opt => \f(CW$val\fP} ] )"
+.IX Subsection "Archive::Tar->iter( $filename, [ $compressed, {opt => $val} ] )"
+Returns an iterator function that reads the tar file without loading
+it all in memory.  Each time the function is called it will return the
+next file in the tarball. The files are returned as
+\&\f(CW\*(C`Archive::Tar::File\*(C'\fR objects. The iterator function returns the
+empty list once it has exhausted the files contained.
+.PP
+The second argument can be a hash reference with options, which are
+identical to the arguments passed to \f(CW\*(C`read()\*(C'\fR.
+.PP
+Example usage:
+.PP
+.Vb 1
+\&    my $next = Archive::Tar\->iter( "example.tar.gz", 1, {filter => qr/\e.pm$/} );
+.Ve
+.PP
+.Vb 2
+\&    while( my $f = $next\->() ) {
+\&        print $f\->name, "\en";
+.Ve
+.PP
+.Vb 1
+\&        $f\->extract or warn "Extraction failed";
+.Ve
+.PP
+.Vb 2
+\&        # ....
+\&    }
+.Ve
+.ie n .Sh "Archive::Tar\->list_archive($file, $compressed, [\e@properties])"
+.el .Sh "Archive::Tar\->list_archive($file, \f(CW$compressed\fP, [\e@properties])"
+.IX Subsection "Archive::Tar->list_archive($file, $compressed, [@properties])"
+Returns a list of the names of all the files in the archive.  The
+first argument can either be the name of the tar file to list or a
+reference to an open file handle (e.g. a \s-1GLOB\s0 reference).
+.PP
+If \f(CW\*(C`list_archive()\*(C'\fR is passed an array reference as its third
+argument it returns a list of hash references containing the requested
+properties of each file.  The following list of properties is
+supported: full_path, name, size, mtime (last modified date), mode,
+uid, gid, linkname, uname, gname, devmajor, devminor, prefix.
+.PP
+See \f(CW\*(C`Archive::Tar::File\*(C'\fR for details about supported properties.
+.PP
+Passing an array reference containing only one element, 'name', is
+special cased to return a list of names rather than a list of hash
+references.
+.ie n .Sh "Archive::Tar\->extract_archive($file, $compressed)"
+.el .Sh "Archive::Tar\->extract_archive($file, \f(CW$compressed\fP)"
+.IX Subsection "Archive::Tar->extract_archive($file, $compressed)"
+Extracts the contents of the tar file.  The first argument can either
+be the name of the tar file to create or a reference to an open file
+handle (e.g. a \s-1GLOB\s0 reference).  All relative paths in the tar file will
+be created underneath the current working directory.
+.PP
+\&\f(CW\*(C`extract_archive\*(C'\fR will return a list of files it extracted.
+If the archive extraction fails for any reason, \f(CW\*(C`extract_archive\*(C'\fR
+will return false.  Please use the \f(CW\*(C`error\*(C'\fR method to find the cause
+of the failure.
+.Sh "$bool = Archive::Tar\->has_io_string"
+.IX Subsection "$bool = Archive::Tar->has_io_string"
+Returns true if we currently have \f(CW\*(C`IO::String\*(C'\fR support loaded.
+.PP
+Either \f(CW\*(C`IO::String\*(C'\fR or \f(CW\*(C`perlio\*(C'\fR support is needed to support writing
+stringified archives. Currently, \f(CW\*(C`perlio\*(C'\fR is the preferred method, if
+available.
+.PP
+See the \f(CW\*(C`GLOBAL VARIABLES\*(C'\fR section to see how to change this preference.
+.Sh "$bool = Archive::Tar\->has_perlio"
+.IX Subsection "$bool = Archive::Tar->has_perlio"
+Returns true if we currently have \f(CW\*(C`perlio\*(C'\fR support loaded.
+.PP
+This requires \f(CW\*(C`perl\-5.8\*(C'\fR or higher, compiled with \f(CW\*(C`perlio\*(C'\fR
+.PP
+Either \f(CW\*(C`IO::String\*(C'\fR or \f(CW\*(C`perlio\*(C'\fR support is needed to support writing
+stringified archives. Currently, \f(CW\*(C`perlio\*(C'\fR is the preferred method, if
+available.
+.PP
+See the \f(CW\*(C`GLOBAL VARIABLES\*(C'\fR section to see how to change this preference.
+.Sh "$bool = Archive::Tar\->has_zlib_support"
+.IX Subsection "$bool = Archive::Tar->has_zlib_support"
+Returns true if \f(CW\*(C`Archive::Tar\*(C'\fR can extract \f(CW\*(C`zlib\*(C'\fR compressed archives
+.Sh "$bool = Archive::Tar\->has_bzip2_support"
+.IX Subsection "$bool = Archive::Tar->has_bzip2_support"
+Returns true if \f(CW\*(C`Archive::Tar\*(C'\fR can extract \f(CW\*(C`bzip2\*(C'\fR compressed archives
+.Sh "Archive::Tar\->can_handle_compressed_files"
+.IX Subsection "Archive::Tar->can_handle_compressed_files"
+A simple checking routine, which will return true if \f(CW\*(C`Archive::Tar\*(C'\fR
+is able to uncompress compressed archives on the fly with \f(CW\*(C`IO::Zlib\*(C'\fR
+and \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR or false if not both are installed.
+.PP
+You can use this as a shortcut to determine whether \f(CW\*(C`Archive::Tar\*(C'\fR
+will do what you think before passing compressed archives to its
+\&\f(CW\*(C`read\*(C'\fR method.
+.SH "GLOBAL VARIABLES"
+.IX Header "GLOBAL VARIABLES"
+.Sh "$Archive::Tar::FOLLOW_SYMLINK"
+.IX Subsection "$Archive::Tar::FOLLOW_SYMLINK"
+Set this variable to \f(CW1\fR to make \f(CW\*(C`Archive::Tar\*(C'\fR effectively make a
+copy of the file when extracting. Default is \f(CW0\fR, which
+means the symlink stays intact. Of course, you will have to pack the
+file linked to as well.
+.PP
+This option is checked when you write out the tarfile using \f(CW\*(C`write\*(C'\fR
+or \f(CW\*(C`create_archive\*(C'\fR.
+.PP
+This works just like \f(CW\*(C`/bin/tar\*(C'\fR's \f(CW\*(C`\-h\*(C'\fR option.
+.Sh "$Archive::Tar::CHOWN"
+.IX Subsection "$Archive::Tar::CHOWN"
+By default, \f(CW\*(C`Archive::Tar\*(C'\fR will try to \f(CW\*(C`chown\*(C'\fR your files if it is
+able to. In some cases, this may not be desired. In that case, set
+this variable to \f(CW0\fR to disable \f(CW\*(C`chown\*(C'\fR\-ing, even if it were
+possible.
+.PP
+The default is \f(CW1\fR.
+.Sh "$Archive::Tar::CHMOD"
+.IX Subsection "$Archive::Tar::CHMOD"
+By default, \f(CW\*(C`Archive::Tar\*(C'\fR will try to \f(CW\*(C`chmod\*(C'\fR your files to
+whatever mode was specified for the particular file in the archive.
+In some cases, this may not be desired. In that case, set this
+variable to \f(CW0\fR to disable \f(CW\*(C`chmod\*(C'\fR\-ing.
+.PP
+The default is \f(CW1\fR.
+.Sh "$Archive::Tar::SAME_PERMISSIONS"
+.IX Subsection "$Archive::Tar::SAME_PERMISSIONS"
+When, \f(CW$Archive::Tar::CHMOD\fR is enabled, this setting controls whether
+the permissions on files from the archive are used without modification
+of if they are filtered by removing any setid bits and applying the
+current umask.
+.PP
+The default is \f(CW1\fR for the root user and \f(CW0\fR for normal users.
+.Sh "$Archive::Tar::DO_NOT_USE_PREFIX"
+.IX Subsection "$Archive::Tar::DO_NOT_USE_PREFIX"
+By default, \f(CW\*(C`Archive::Tar\*(C'\fR will try to put paths that are over
+100 characters in the \f(CW\*(C`prefix\*(C'\fR field of your tar header, as
+defined per POSIX\-standard. However, some (older) tar programs
+do not implement this spec. To retain compatibility with these older
+or non-POSIX compliant versions, you can set the \f(CW$DO_NOT_USE_PREFIX\fR
+variable to a true value, and \f(CW\*(C`Archive::Tar\*(C'\fR will use an alternate
+way of dealing with paths over 100 characters by using the
+\&\f(CW\*(C`GNU Extended Header\*(C'\fR feature.
+.PP
+Note that clients who do not support the \f(CW\*(C`GNU Extended Header\*(C'\fR
+feature will not be able to read these archives. Such clients include
+tars on \f(CW\*(C`Solaris\*(C'\fR, \f(CW\*(C`Irix\*(C'\fR and \f(CW\*(C`AIX\*(C'\fR.
+.PP
+The default is \f(CW0\fR.
+.Sh "$Archive::Tar::DEBUG"
+.IX Subsection "$Archive::Tar::DEBUG"
+Set this variable to \f(CW1\fR to always get the \f(CW\*(C`Carp::longmess\*(C'\fR output
+of the warnings, instead of the regular \f(CW\*(C`carp\*(C'\fR. This is the same
+message you would get by doing:
+.PP
+.Vb 1
+\&    $tar\->error(1);
+.Ve
+.PP
+Defaults to \f(CW0\fR.
+.Sh "$Archive::Tar::WARN"
+.IX Subsection "$Archive::Tar::WARN"
+Set this variable to \f(CW0\fR if you do not want any warnings printed.
+Personally I recommend against doing this, but people asked for the
+option. Also, be advised that this is of course not threadsafe.
+.PP
+Defaults to \f(CW1\fR.
+.Sh "$Archive::Tar::error"
+.IX Subsection "$Archive::Tar::error"
+Holds the last reported error. Kept for historical reasons, but its
+use is very much discouraged. Use the \f(CW\*(C`error()\*(C'\fR method instead:
+.PP
+.Vb 1
+\&    warn $tar\->error unless $tar\->extract;
+.Ve
+.PP
+Note that in older versions of this module, the \f(CW\*(C`error()\*(C'\fR method
+would return an effectively global value even when called an instance
+method as above. This has since been fixed, and multiple instances of
+\&\f(CW\*(C`Archive::Tar\*(C'\fR now have separate error strings.
+.Sh "$Archive::Tar::INSECURE_EXTRACT_MODE"
+.IX Subsection "$Archive::Tar::INSECURE_EXTRACT_MODE"
+This variable indicates whether \f(CW\*(C`Archive::Tar\*(C'\fR should allow
+files to be extracted outside their current working directory.
+.PP
+Allowing this could have security implications, as a malicious
+tar archive could alter or replace any file the extracting user
+has permissions to. Therefor, the default is to not allow
+insecure extractions.
+.PP
+If you trust the archive, or have other reasons to allow the
+archive to write files outside your current working directory,
+set this variable to \f(CW\*(C`true\*(C'\fR.
+.PP
+Note that this is a backwards incompatible change from version
+\&\f(CW1.36\fR and before.
+.Sh "$Archive::Tar::HAS_PERLIO"
+.IX Subsection "$Archive::Tar::HAS_PERLIO"
+This variable holds a boolean indicating if we currently have
+\&\f(CW\*(C`perlio\*(C'\fR support loaded. This will be enabled for any perl
+greater than \f(CW5.8\fR compiled with \f(CW\*(C`perlio\*(C'\fR.
+.PP
+If you feel strongly about disabling it, set this variable to
+\&\f(CW\*(C`false\*(C'\fR. Note that you will then need \f(CW\*(C`IO::String\*(C'\fR installed
+to support writing stringified archives.
+.PP
+Don't change this variable unless you \fBreally\fR know what you're
+doing.
+.Sh "$Archive::Tar::HAS_IO_STRING"
+.IX Subsection "$Archive::Tar::HAS_IO_STRING"
+This variable holds a boolean indicating if we currently have
+\&\f(CW\*(C`IO::String\*(C'\fR support loaded. This will be enabled for any perl
+that has a loadable \f(CW\*(C`IO::String\*(C'\fR module.
+.PP
+If you feel strongly about disabling it, set this variable to
+\&\f(CW\*(C`false\*(C'\fR. Note that you will then need \f(CW\*(C`perlio\*(C'\fR support from
+your perl to be able to  write stringified archives.
+.PP
+Don't change this variable unless you \fBreally\fR know what you're
+doing.
+.SH "FAQ"
+.IX Header "FAQ"
+.IP "What's the minimum perl version required to run Archive::Tar?" 4
+.IX Item "What's the minimum perl version required to run Archive::Tar?"
+You will need perl version 5.005_03 or newer.
+.IP "Isn't Archive::Tar slow?" 4
+.IX Item "Isn't Archive::Tar slow?"
+Yes it is. It's pure perl, so it's a lot slower then your \f(CW\*(C`/bin/tar\*(C'\fR
+However, it's very portable. If speed is an issue, consider using
+\&\f(CW\*(C`/bin/tar\*(C'\fR instead.
+.IP "Isn't Archive::Tar heavier on memory than /bin/tar?" 4
+.IX Item "Isn't Archive::Tar heavier on memory than /bin/tar?"
+Yes it is, see previous answer. Since \f(CW\*(C`Compress::Zlib\*(C'\fR and therefore
+\&\f(CW\*(C`IO::Zlib\*(C'\fR doesn't support \f(CW\*(C`seek\*(C'\fR on their filehandles, there is little
+choice but to read the archive into memory.
+This is ok if you want to do in-memory manipulation of the archive.
+.Sp
+If you just want to extract, use the \f(CW\*(C`extract_archive\*(C'\fR class method
+instead. It will optimize and write to disk immediately.
+.Sp
+Another option is to use the \f(CW\*(C`iter\*(C'\fR class method to iterate over
+the files in the tarball without reading them all in memory at once.
+.IP "Can you lazy-load data instead?" 4
+.IX Item "Can you lazy-load data instead?"
+In some cases, yes. You can use the \f(CW\*(C`iter\*(C'\fR class method to iterate
+over the files in the tarball without reading them all in memory at once.
+.IP "How much memory will an X kb tar file need?" 4
+.IX Item "How much memory will an X kb tar file need?"
+Probably more than X kb, since it will all be read into memory. If
+this is a problem, and you don't need to do in memory manipulation
+of the archive, consider using the \f(CW\*(C`iter\*(C'\fR class method, or \f(CW\*(C`/bin/tar\*(C'\fR
+instead.
+.IP "What do you do with unsupported filetypes in an archive?" 4
+.IX Item "What do you do with unsupported filetypes in an archive?"
+\&\f(CW\*(C`Unix\*(C'\fR has a few filetypes that aren't supported on other platforms,
+like \f(CW\*(C`Win32\*(C'\fR. If we encounter a \f(CW\*(C`hardlink\*(C'\fR or \f(CW\*(C`symlink\*(C'\fR we'll just
+try to make a copy of the original file, rather than throwing an error.
+.Sp
+This does require you to read the entire archive in to memory first,
+since otherwise we wouldn't know what data to fill the copy with.
+(This means that you cannot use the class methods, including \f(CW\*(C`iter\*(C'\fR
+on archives that have incompatible filetypes and still expect things
+to work).
+.Sp
+For other filetypes, like \f(CW\*(C`chardevs\*(C'\fR and \f(CW\*(C`blockdevs\*(C'\fR we'll warn that
+the extraction of this particular item didn't work.
+.IP "I'm using WinZip, or some other non-POSIX client, and files are not being extracted properly!" 4
+.IX Item "I'm using WinZip, or some other non-POSIX client, and files are not being extracted properly!"
+By default, \f(CW\*(C`Archive::Tar\*(C'\fR is in a completely POSIX-compatible
+mode, which uses the POSIX-specification of \f(CW\*(C`tar\*(C'\fR to store files.
+For paths greather than 100 characters, this is done using the
+\&\f(CW\*(C`POSIX header prefix\*(C'\fR. Non-POSIX-compatible clients may not support
+this part of the specification, and may only support the \f(CW\*(C`GNU Extended
+Header\*(C'\fR functionality. To facilitate those clients, you can set the
+\&\f(CW$Archive::Tar::DO_NOT_USE_PREFIX\fR variable to \f(CW\*(C`true\*(C'\fR. See the
+\&\f(CW\*(C`GLOBAL VARIABLES\*(C'\fR section for details on this variable.
+.Sp
+Note that \s-1GNU\s0 tar earlier than version 1.14 does not cope well with
+the \f(CW\*(C`POSIX header prefix\*(C'\fR. If you use such a version, consider setting
+the \f(CW$Archive::Tar::DO_NOT_USE_PREFIX\fR variable to \f(CW\*(C`true\*(C'\fR.
+.IP "How do I extract only files that have property X from an archive?" 4
+.IX Item "How do I extract only files that have property X from an archive?"
+Sometimes, you might not wish to extract a complete archive, just
+the files that are relevant to you, based on some criteria.
+.Sp
+You can do this by filtering a list of \f(CW\*(C`Archive::Tar::File\*(C'\fR objects
+based on your criteria. For example, to extract only files that have
+the string \f(CW\*(C`foo\*(C'\fR in their title, you would use:
+.Sp
+.Vb 3
+\&    $tar\->extract(
+\&        grep { $_\->full_path =~ /foo/ } $tar\->get_files
+\&    );
+.Ve
+.Sp
+This way, you can filter on any attribute of the files in the archive.
+Consult the \f(CW\*(C`Archive::Tar::File\*(C'\fR documentation on how to use these
+objects.
+.IP "How do I access .tar.Z files?" 4
+.IX Item "How do I access .tar.Z files?"
+The \f(CW\*(C`Archive::Tar\*(C'\fR module can optionally use \f(CW\*(C`Compress::Zlib\*(C'\fR (via
+the \f(CW\*(C`IO::Zlib\*(C'\fR module) to access tar files that have been compressed
+with \f(CW\*(C`gzip\*(C'\fR. Unfortunately tar files compressed with the Unix \f(CW\*(C`compress\*(C'\fR
+utility cannot be read by \f(CW\*(C`Compress::Zlib\*(C'\fR and so cannot be directly
+accesses by \f(CW\*(C`Archive::Tar\*(C'\fR.
+.Sp
+If the \f(CW\*(C`uncompress\*(C'\fR or \f(CW\*(C`gunzip\*(C'\fR programs are available, you can use
+one of these workarounds to read \f(CW\*(C`.tar.Z\*(C'\fR files from \f(CW\*(C`Archive::Tar\*(C'\fR
+.Sp
+Firstly with \f(CW\*(C`uncompress\*(C'\fR
+.Sp
+.Vb 1
+\&    use Archive::Tar;
+.Ve
+.Sp
+.Vb 3
+\&    open F, "uncompress \-c $filename |";
+\&    my $tar = Archive::Tar\->new(*F);
+\&    ...
+.Ve
+.Sp
+and this with \f(CW\*(C`gunzip\*(C'\fR
+.Sp
+.Vb 1
+\&    use Archive::Tar;
+.Ve
+.Sp
+.Vb 3
+\&    open F, "gunzip \-c $filename |";
+\&    my $tar = Archive::Tar\->new(*F);
+\&    ...
+.Ve
+.Sp
+Similarly, if the \f(CW\*(C`compress\*(C'\fR program is available, you can use this to
+write a \f(CW\*(C`.tar.Z\*(C'\fR file
+.Sp
+.Vb 2
+\&    use Archive::Tar;
+\&    use IO::File;
+.Ve
+.Sp
+.Vb 5
+\&    my $fh = new IO::File "| compress \-c >$filename";
+\&    my $tar = Archive::Tar\->new();
+\&    ...
+\&    $tar\->write($fh);
+\&    $fh\->close ;
+.Ve
+.IP "How do I handle Unicode strings?" 4
+.IX Item "How do I handle Unicode strings?"
+\&\f(CW\*(C`Archive::Tar\*(C'\fR uses byte semantics for any files it reads from or writes
+to disk. This is not a problem if you only deal with files and never
+look at their content or work solely with byte strings. But if you use
+Unicode strings with character semantics, some additional steps need
+to be taken.
+.Sp
+For example, if you add a Unicode string like
+.Sp
+.Vb 2
+\&    # Problem
+\&    $tar\->add_data('file.txt', "Euro: \ex{20AC}");
+.Ve
+.Sp
+then there will be a problem later when the tarfile gets written out
+to disk via \f(CW\*(C`$tar\-\*(C'\fR\fIwrite()\fR>:
+.Sp
+.Vb 1
+\&    Wide character in print at .../Archive/Tar.pm line 1014.
+.Ve
+.Sp
+The data was added as a Unicode string and when writing it out to disk,
+the \f(CW\*(C`:utf8\*(C'\fR line discipline wasn't set by \f(CW\*(C`Archive::Tar\*(C'\fR, so Perl
+tried to convert the string to \s-1ISO\-8859\s0 and failed. The written file
+now contains garbage.
+.Sp
+For this reason, Unicode strings need to be converted to UTF\-8\-encoded
+bytestrings before they are handed off to \f(CW\*(C`add_data()\*(C'\fR:
+.Sp
+.Vb 3
+\&    use Encode;
+\&    my $data = "Accented character: \ex{20AC}";
+\&    $data = encode('utf8', $data);
+.Ve
+.Sp
+.Vb 1
+\&    $tar\->add_data('file.txt', $data);
+.Ve
+.Sp
+A opposite problem occurs if you extract a UTF8\-encoded file from a
+tarball. Using \f(CW\*(C`get_content()\*(C'\fR on the \f(CW\*(C`Archive::Tar::File\*(C'\fR object
+will return its content as a bytestring, not as a Unicode string.
+.Sp
+If you want it to be a Unicode string (because you want character
+semantics with operations like regular expression matching), you need
+to decode the UTF8\-encoded content and have Perl convert it into
+a Unicode string:
+.Sp
+.Vb 2
+\&    use Encode;
+\&    my $data = $tar\->get_content();
+.Ve
+.Sp
+.Vb 2
+\&    # Make it a Unicode string
+\&    $data = decode('utf8', $data);
+.Ve
+.Sp
+There is no easy way to provide this functionality in \f(CW\*(C`Archive::Tar\*(C'\fR,
+because a tarball can contain many files, and each of which could be
+encoded in a different way.
+.SH "CAVEATS"
+.IX Header "CAVEATS"
+The \s-1AIX\s0 tar does not fill all unused space in the tar archive with 0x00. 
+This sometimes leads to warning messages from \f(CW\*(C`Archive::Tar\*(C'\fR.
+.PP
+.Vb 1
+\&  Invalid header block at offset nnn
+.Ve
+.PP
+A fix for that problem is scheduled to be released in the following levels
+of \s-1AIX\s0, all of which should be coming out in the 4th quarter of 2009:
+.PP
+.Vb 4
+\& AIX 5.3 TL7 SP10
+\& AIX 5.3 TL8 SP8
+\& AIX 5.3 TL9 SP5
+\& AIX 5.3 TL10 SP2
+.Ve
+.PP
+.Vb 4
+\& AIX 6.1 TL0 SP11
+\& AIX 6.1 TL1 SP7
+\& AIX 6.1 TL2 SP6
+\& AIX 6.1 TL3 SP3
+.Ve
+.PP
+The \s-1IBM\s0 \s-1APAR\s0 number for this problem is \s-1IZ50240\s0 (Reported component \s-1ID:\s0 
+5765G0300 / \s-1AIX\s0 5.3). It is possible to get an ifix for that problem. 
+If you need an ifix please contact your local \s-1IBM\s0 \s-1AIX\s0 support.
+.SH "TODO"
+.IX Header "TODO"
+.IP "Check if passed in handles are open for read/write" 4
+.IX Item "Check if passed in handles are open for read/write"
+Currently I don't know of any portable pure perl way to do this.
+Suggestions welcome.
+.IP "Allow archives to be passed in as string" 4
+.IX Item "Allow archives to be passed in as string"
+Currently, we only allow opened filehandles or filenames, but
+not strings. The internals would need some reworking to facilitate
+stringified archives.
+.IP "Facilitate processing an opened filehandle of a compressed archive" 4
+.IX Item "Facilitate processing an opened filehandle of a compressed archive"
+Currently, we only support this if the filehandle is an IO::Zlib object.
+Environments, like apache, will present you with an opened filehandle
+to an uploaded file, which might be a compressed archive.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+.IP "The \s-1GNU\s0 tar specification" 4
+.IX Item "The GNU tar specification"
+\&\f(CW\*(C`http://www.gnu.org/software/tar/manual/tar.html\*(C'\fR
+.IP "The \s-1PAX\s0 format specication" 4
+.IX Item "The PAX format specication"
+The specifcation which tar derives from; \f(CW\*(C` http://www.opengroup.org/onlinepubs/007904975/utilities/pax.html\*(C'\fR
+.ie n .IP "A comparison of \s-1GNU\s0 and \s-1POSIX\s0 tar standards; ""http://www.delorie.com/gnu/docs/tar/tar_114.html""" 4
+.el .IP "A comparison of \s-1GNU\s0 and \s-1POSIX\s0 tar standards; \f(CWhttp://www.delorie.com/gnu/docs/tar/tar_114.html\fR" 4
+.IX Item "A comparison of GNU and POSIX tar standards; http://www.delorie.com/gnu/docs/tar/tar_114.html"
+.PD 0
+.IP "\s-1GNU\s0 tar intends to switch to \s-1POSIX\s0 compatibility" 4
+.IX Item "GNU tar intends to switch to POSIX compatibility"
+.PD
+\&\s-1GNU\s0 Tar authors have expressed their intention to become completely
+POSIX\-compatible; \f(CW\*(C`http://www.gnu.org/software/tar/manual/html_node/Formats.html\*(C'\fR
+.IP "A Comparison between various tar implementations" 4
+.IX Item "A Comparison between various tar implementations"
+Lists known issues and incompatibilities; \f(CW\*(C`http://gd.tuwien.ac.at/utils/archivers/star/README.otherbugs\*(C'\fR
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+This module by Jos Boumans <kane@cpan.org>.
+.PP
+Please reports bugs to <bug\-archive\-tar@rt.cpan.org>.
+.SH "ACKNOWLEDGEMENTS"
+.IX Header "ACKNOWLEDGEMENTS"
+Thanks to Sean Burke, Chris Nandor, Chip Salzenberg, Tim Heaney, Gisle Aas,
+Rainer Tammer and especially Andrew Savige for their help and suggestions.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+This module is copyright (c) 2002 \- 2009 Jos Boumans
+<kane@cpan.org>. All rights reserved.
+.PP
+This library is free software; you may redistribute and/or modify
+it under the same terms as Perl itself.