local-lib5/man/man3/Archive::Tar.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Archive::Tar 3"
 132 .TH Archive::Tar 3 "2009-09-10" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Archive::Tar \- module for manipulations of tar archives
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 2
 138 \&    use Archive::Tar;
 139 \&    my $tar = Archive::Tar\->new;
 140 .Ve
 141 .PP
 142 .Vb 2
 143 \&    $tar\->read('origin.tgz');
 144 \&    $tar\->extract();
 145 .Ve
 146 .PP
 147 .Vb 2
 148 \&    $tar\->add_files('file/foo.pl', 'docs/README');
 149 \&    $tar\->add_data('file/baz.txt', 'This is the contents now');
 150 .Ve
 151 .PP
 152 .Vb 1
 153 \&    $tar\->rename('oldname', 'new/file/name');
 154 .Ve
 155 .PP
 156 .Vb 3
 157 \&    $tar\->write('files.tar');                   # plain tar
 158 \&    $tar\->write('files.tgz', COMPRESS_GZIP);    # gzip compressed
 159 \&    $tar\->write('files.tbz', COMPRESS_BZIP);    # bzip2 compressed
 160 .Ve
 161 .SH "DESCRIPTION"
 162 .IX Header "DESCRIPTION"
 163 Archive::Tar provides an object oriented mechanism for handling tar
 164 files.  It provides class methods for quick and easy files handling
 165 while also allowing for the creation of tar file objects for custom
 166 manipulation.  If you have the IO::Zlib module installed,
 167 Archive::Tar will also support compressed or gzipped tar files.
 168 .PP
 169 An object of class Archive::Tar represents a .tar(.gz) archive full
 170 of files and things.
 171 .SH "Object Methods"
 172 .IX Header "Object Methods"
 173 .ie n .Sh "Archive::Tar\->new( [$file, $compressed] )"
 174 .el .Sh "Archive::Tar\->new( [$file, \f(CW$compressed\fP] )"
 175 .IX Subsection "Archive::Tar->new( [$file, $compressed] )"
 176 Returns a new Tar object. If given any arguments, \f(CW\*(C`new()\*(C'\fR calls the
 177 \&\f(CW\*(C`read()\*(C'\fR method automatically, passing on the arguments provided to
 178 the \f(CW\*(C`read()\*(C'\fR method.
 179 .PP
 180 If \f(CW\*(C`new()\*(C'\fR is invoked with arguments and the \f(CW\*(C`read()\*(C'\fR method fails
 181 for any reason, \f(CW\*(C`new()\*(C'\fR returns undef.
 182 .ie n .Sh "$tar\->read ( $filename|$handle, [$compressed, {opt => 'val'}] )"
 183 .el .Sh "$tar\->read ( \f(CW$filename\fP|$handle, [$compressed, {opt => 'val'}] )"
 184 .IX Subsection "$tar->read ( $filename|$handle, [$compressed, {opt => 'val'}] )"
 185 Read the given tar file into memory.
 186 The first argument can either be the name of a file or a reference to
 187 an already open filehandle (or an IO::Zlib object if it's compressed)
 188 .PP
 189 The \f(CW\*(C`read\*(C'\fR will \fIreplace\fR any previous content in \f(CW$tar\fR!
 190 .PP
 191 The second argument may be considered optional, but remains for
 192 backwards compatibility. Archive::Tar now looks at the file
 193 magic to determine what class should be used to open the file
 194 and will transparently Do The Right Thing.
 195 .PP
 196 Archive::Tar will warn if you try to pass a bzip2 compressed file and the
 197 IO::Zlib / IO::Uncompress::Bunzip2 modules are not available and simply return.
 198 .PP
 199 Note that you can currently \fBnot\fR pass a \f(CW\*(C`gzip\*(C'\fR compressed
 200 filehandle, which is not opened with \f(CW\*(C`IO::Zlib\*(C'\fR, a \f(CW\*(C`bzip2\*(C'\fR compressed
 201 filehandle, which is not opened with \f(CW\*(C`IO::Uncompress::Bunzip2\*(C'\fR, nor a string
 202 containing the full archive information (either compressed or
 203 uncompressed). These are worth while features, but not currently
 204 implemented. See the \f(CW\*(C`TODO\*(C'\fR section.
 205 .PP
 206 The third argument can be a hash reference with options. Note that
 207 all options are case\-sensitive.
 208 .IP "limit" 4
 209 .IX Item "limit"
 210 Do not read more than \f(CW\*(C`limit\*(C'\fR files. This is useful if you have
 211 very big archives, and are only interested in the first few files.
 212 .IP "filter" 4
 213 .IX Item "filter"
 214 Can be set to a regular expression.  Only files with names that match
 215 the expression will be read.
 216 .IP "extract" 4
 217 .IX Item "extract"
 218 If set to true, immediately extract entries when reading them. This
 219 gives you the same memory break as the \f(CW\*(C`extract_archive\*(C'\fR function.
 220 Note however that entries will not be read into memory, but written
 221 straight to disk. This means no \f(CW\*(C`Archive::Tar::File\*(C'\fR objects are
 222 created for you to inspect.
 223 .PP
 224 All files are stored internally as \f(CW\*(C`Archive::Tar::File\*(C'\fR objects.
 225 Please consult the Archive::Tar::File documentation for details.
 226 .PP
 227 Returns the number of files read in scalar context, and a list of
 228 \&\f(CW\*(C`Archive::Tar::File\*(C'\fR objects in list context.
 229 .ie n .Sh "$tar\->contains_file( $filename )"
 230 .el .Sh "$tar\->contains_file( \f(CW$filename\fP )"
 231 .IX Subsection "$tar->contains_file( $filename )"
 232 Check if the archive contains a certain file.
 233 It will return true if the file is in the archive, false otherwise.
 234 .PP
 235 Note however, that this function does an exact match using \f(CW\*(C`eq\*(C'\fR
 236 on the full path. So it cannot compensate for case-insensitive file\-
 237 systems or compare 2 paths to see if they would point to the same
 238 underlying file.
 239 .Sh "$tar\->extract( [@filenames] )"
 240 .IX Subsection "$tar->extract( [@filenames] )"
 241 Write files whose names are equivalent to any of the names in
 242 \&\f(CW@filenames\fR to disk, creating subdirectories as necessary. This
 243 might not work too well under \s-1VMS\s0.
 244 Under MacPerl, the file's modification time will be converted to the
 245 MacOS zero of time, and appropriate conversions will be done to the
 246 path.  However, the length of each element of the path is not
 247 inspected to see whether it's longer than MacOS currently allows (32
 248 characters).
 249 .PP
 250 If \f(CW\*(C`extract\*(C'\fR is called without a list of file names, the entire
 251 contents of the archive are extracted.
 252 .PP
 253 Returns a list of filenames extracted.
 254 .ie n .Sh "$tar\->extract_file( $file, [$extract_path] )"
 255 .el .Sh "$tar\->extract_file( \f(CW$file\fP, [$extract_path] )"
 256 .IX Subsection "$tar->extract_file( $file, [$extract_path] )"
 257 Write an entry, whose name is equivalent to the file name provided to
 258 disk. Optionally takes a second parameter, which is the full native
 259 path (including filename) the entry will be written to.
 260 .PP
 261 For example:
 262 .PP
 263 .Vb 1
 264 \&    $tar\->extract_file( 'name/in/archive', 'name/i/want/to/give/it' );
 265 .Ve
 266 .PP
 267 .Vb 1
 268 \&    $tar\->extract_file( $at_file_object,   'name/i/want/to/give/it' );
 269 .Ve
 270 .PP
 271 Returns true on success, false on failure.
 272 .Sh "$tar\->list_files( [\e@properties] )"
 273 .IX Subsection "$tar->list_files( [@properties] )"
 274 Returns a list of the names of all the files in the archive.
 275 .PP
 276 If \f(CW\*(C`list_files()\*(C'\fR is passed an array reference as its first argument
 277 it returns a list of hash references containing the requested
 278 properties of each file.  The following list of properties is
 279 supported: name, size, mtime (last modified date), mode, uid, gid,
 280 linkname, uname, gname, devmajor, devminor, prefix.
 281 .PP
 282 Passing an array reference containing only one element, 'name', is
 283 special cased to return a list of names rather than a list of hash
 284 references, making it equivalent to calling \f(CW\*(C`list_files\*(C'\fR without
 285 arguments.
 286 .Sh "$tar\->get_files( [@filenames] )"
 287 .IX Subsection "$tar->get_files( [@filenames] )"
 288 Returns the \f(CW\*(C`Archive::Tar::File\*(C'\fR objects matching the filenames
 289 provided. If no filename list was passed, all \f(CW\*(C`Archive::Tar::File\*(C'\fR
 290 objects in the current Tar object are returned.
 291 .PP
 292 Please refer to the \f(CW\*(C`Archive::Tar::File\*(C'\fR documentation on how to
 293 handle these objects.
 294 .ie n .Sh "$tar\->get_content( $file )"
 295 .el .Sh "$tar\->get_content( \f(CW$file\fP )"
 296 .IX Subsection "$tar->get_content( $file )"
 297 Return the content of the named file.
 298 .ie n .Sh "$tar\->replace_content( $file\fP, \f(CW$content )"
 299 .el .Sh "$tar\->replace_content( \f(CW$file\fP, \f(CW$content\fP )"
 300 .IX Subsection "$tar->replace_content( $file, $content )"
 301 Make the string \f(CW$content\fR be the content for the file named \f(CW$file\fR.
 302 .ie n .Sh "$tar\->rename( $file\fP, \f(CW$new_name )"
 303 .el .Sh "$tar\->rename( \f(CW$file\fP, \f(CW$new_name\fP )"
 304 .IX Subsection "$tar->rename( $file, $new_name )"
 305 Rename the file of the in-memory archive to \f(CW$new_name\fR.
 306 .PP
 307 Note that you must specify a Unix path for \f(CW$new_name\fR, since per tar
 308 standard, all files in the archive must be Unix paths.
 309 .PP
 310 Returns true on success and false on failure.
 311 .Sh "$tar\->remove (@filenamelist)"
 312 .IX Subsection "$tar->remove (@filenamelist)"
 313 Removes any entries with names matching any of the given filenames
 314 from the in-memory archive. Returns a list of \f(CW\*(C`Archive::Tar::File\*(C'\fR
 315 objects that remain.
 316 .Sh "$tar\->clear"
 317 .IX Subsection "$tar->clear"
 318 \&\f(CW\*(C`clear\*(C'\fR clears the current in-memory archive. This effectively gives
 319 you a 'blank' object, ready to be filled again. Note that \f(CW\*(C`clear\*(C'\fR
 320 only has effect on the object, not the underlying tarfile.
 321 .ie n .Sh "$tar\->write ( [$file, $compressed\fP, \f(CW$prefix] )"
 322 .el .Sh "$tar\->write ( [$file, \f(CW$compressed\fP, \f(CW$prefix\fP] )"
 323 .IX Subsection "$tar->write ( [$file, $compressed, $prefix] )"
 324 Write the in-memory archive to disk.  The first argument can either
 325 be the name of a file or a reference to an already open filehandle (a
 326 \&\s-1GLOB\s0 reference).
 327 .PP
 328 The second argument is used to indicate compression. You can either
 329 compress using \f(CW\*(C`gzip\*(C'\fR or \f(CW\*(C`bzip2\*(C'\fR. If you pass a digit, it's assumed
 330 to be the \f(CW\*(C`gzip\*(C'\fR compression level (between 1 and 9), but the use of
 331 constants is prefered:
 332 .PP
 333 .Vb 2
 334 \&  # write a gzip compressed file
 335 \&  $tar\->write( 'out.tgz', COMPRESS_GZIP );
 336 .Ve
 337 .PP
 338 .Vb 2
 339 \&  # write a bzip compressed file
 340 \&  $tar\->write( 'out.tbz', COMPRESS_BZIP );
 341 .Ve
 342 .PP
 343 Note that when you pass in a filehandle, the compression argument
 344 is ignored, as all files are printed verbatim to your filehandle.
 345 If you wish to enable compression with filehandles, use an
 346 \&\f(CW\*(C`IO::Zlib\*(C'\fR or \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR filehandle instead.
 347 .PP
 348 The third argument is an optional prefix. All files will be tucked
 349 away in the directory you specify as prefix. So if you have files
 350 \&'a' and 'b' in your archive, and you specify 'foo' as prefix, they
 351 will be written to the archive as 'foo/a' and 'foo/b'.
 352 .PP
 353 If no arguments are given, \f(CW\*(C`write\*(C'\fR returns the entire formatted
 354 archive as a string, which could be useful if you'd like to stuff the
 355 archive into a socket or a pipe to gzip or something.
 356 .ie n .Sh "$tar\->add_files( @filenamelist )"
 357 .el .Sh "$tar\->add_files( \f(CW@filenamelist\fP )"
 358 .IX Subsection "$tar->add_files( @filenamelist )"
 359 Takes a list of filenames and adds them to the in-memory archive.
 360 .PP
 361 The path to the file is automatically converted to a Unix like
 362 equivalent for use in the archive, and, if on MacOS, the file's
 363 modification time is converted from the MacOS epoch to the Unix epoch.
 364 So tar archives created on MacOS with \fBArchive::Tar\fR can be read
 365 both with \fItar\fR on Unix and applications like \fIsuntar\fR or
 366 \&\fIStuffit Expander\fR on MacOS.
 367 .PP
 368 Be aware that the file's type/creator and resource fork will be lost,
 369 which is usually what you want in cross-platform archives.
 370 .PP
 371 Instead of a filename, you can also pass it an existing \f(CW\*(C`Archive::Tar::File\*(C'\fR
 372 object from, for example, another archive. The object will be clone, and
 373 effectively be a copy of the original, not an alias.
 374 .PP
 375 Returns a list of \f(CW\*(C`Archive::Tar::File\*(C'\fR objects that were just added.
 376 .ie n .Sh "$tar\->add_data ( $filename\fP, \f(CW$data, [$opthashref] )"
 377 .el .Sh "$tar\->add_data ( \f(CW$filename\fP, \f(CW$data\fP, [$opthashref] )"
 378 .IX Subsection "$tar->add_data ( $filename, $data, [$opthashref] )"
 379 Takes a filename, a scalar full of data and optionally a reference to
 380 a hash with specific options.
 381 .PP
 382 Will add a file to the in-memory archive, with name \f(CW$filename\fR and
 383 content \f(CW$data\fR. Specific properties can be set using \f(CW$opthashref\fR.
 384 The following list of properties is supported: name, size, mtime
 385 (last modified date), mode, uid, gid, linkname, uname, gname,
 386 devmajor, devminor, prefix, type.  (On MacOS, the file's path and
 387 modification times are converted to Unix equivalents.)
 388 .PP
 389 Valid values for the file type are the following constants defined in
 390 Archive::Tar::Constants:
 391 .IP "\s-1FILE\s0" 4
 392 .IX Item "FILE"
 393 Regular file.
 394 .IP "\s-1HARDLINK\s0" 4
 395 .IX Item "HARDLINK"
 396 .PD 0
 397 .IP "\s-1SYMLINK\s0" 4
 398 .IX Item "SYMLINK"
 399 .PD
 400 Hard and symbolic (\*(L"soft\*(R") links; linkname should specify target.
 401 .IP "\s-1CHARDEV\s0" 4
 402 .IX Item "CHARDEV"
 403 .PD 0
 404 .IP "\s-1BLOCKDEV\s0" 4
 405 .IX Item "BLOCKDEV"
 406 .PD
 407 Character and block devices. devmajor and devminor should specify the major
 408 and minor device numbers.
 409 .IP "\s-1DIR\s0" 4
 410 .IX Item "DIR"
 411 Directory.
 412 .IP "\s-1FIFO\s0" 4
 413 .IX Item "FIFO"
 414 \&\s-1FIFO\s0 (named pipe).
 415 .IP "\s-1SOCKET\s0" 4
 416 .IX Item "SOCKET"
 417 Socket.
 418 .PP
 419 Returns the \f(CW\*(C`Archive::Tar::File\*(C'\fR object that was just added, or
 420 \&\f(CW\*(C`undef\*(C'\fR on failure.
 421 .Sh "$tar\->error( [$BOOL] )"
 422 .IX Subsection "$tar->error( [$BOOL] )"
 423 Returns the current errorstring (usually, the last error reported).
 424 If a true value was specified, it will give the \f(CW\*(C`Carp::longmess\*(C'\fR
 425 equivalent of the error, in effect giving you a stacktrace.
 426 .PP
 427 For backwards compatibility, this error is also available as
 428 \&\f(CW$Archive::Tar::error\fR although it is much recommended you use the
 429 method call instead.
 430 .ie n .Sh "$tar\->setcwd( $cwd );"
 431 .el .Sh "$tar\->setcwd( \f(CW$cwd\fP );"
 432 .IX Subsection "$tar->setcwd( $cwd );"
 433 \&\f(CW\*(C`Archive::Tar\*(C'\fR needs to know the current directory, and it will run
 434 \&\f(CW\*(C`Cwd::cwd()\*(C'\fR \fIevery\fR time it extracts a \fIrelative\fR entry from the
 435 tarfile and saves it in the file system. (As of version 1.30, however,
 436 \&\f(CW\*(C`Archive::Tar\*(C'\fR will use the speed optimization described below
 437 automatically, so it's only relevant if you're using \f(CW\*(C`extract_file()\*(C'\fR).
 438 .PP
 439 Since \f(CW\*(C`Archive::Tar\*(C'\fR doesn't change the current directory internally
 440 while it is extracting the items in a tarball, all calls to \f(CW\*(C`Cwd::cwd()\*(C'\fR
 441 can be avoided if we can guarantee that the current directory doesn't
 442 get changed externally.
 443 .PP
 444 To use this performance boost, set the current directory via
 445 .PP
 446 .Vb 2
 447 \&    use Cwd;
 448 \&    $tar\->setcwd( cwd() );
 449 .Ve
 450 .PP
 451 once before calling a function like \f(CW\*(C`extract_file\*(C'\fR and
 452 \&\f(CW\*(C`Archive::Tar\*(C'\fR will use the current directory setting from then on
 453 and won't call \f(CW\*(C`Cwd::cwd()\*(C'\fR internally.
 454 .PP
 455 To switch back to the default behaviour, use
 456 .PP
 457 .Vb 1
 458 \&    $tar\->setcwd( undef );
 459 .Ve
 460 .PP
 461 and \f(CW\*(C`Archive::Tar\*(C'\fR will call \f(CW\*(C`Cwd::cwd()\*(C'\fR internally again.
 462 .PP
 463 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
 464 be called for you.
 465 .SH "Class Methods"
 466 .IX Header "Class Methods"
 467 .ie n .Sh "Archive::Tar\->create_archive($file, $compressed\fP, \f(CW@filelist)"
 468 .el .Sh "Archive::Tar\->create_archive($file, \f(CW$compressed\fP, \f(CW@filelist\fP)"
 469 .IX Subsection "Archive::Tar->create_archive($file, $compressed, @filelist)"
 470 Creates a tar file from the list of files provided.  The first
 471 argument can either be the name of the tar file to create or a
 472 reference to an open file handle (e.g. a \s-1GLOB\s0 reference).
 473 .PP
 474 The second argument is used to indicate compression. You can either
 475 compress using \f(CW\*(C`gzip\*(C'\fR or \f(CW\*(C`bzip2\*(C'\fR. If you pass a digit, it's assumed
 476 to be the \f(CW\*(C`gzip\*(C'\fR compression level (between 1 and 9), but the use of
 477 constants is prefered:
 478 .PP
 479 .Vb 2
 480 \&  # write a gzip compressed file
 481 \&  Archive::Tar\->create_archive( 'out.tgz', COMPRESS_GZIP, @filelist );
 482 .Ve
 483 .PP
 484 .Vb 2
 485 \&  # write a bzip compressed file
 486 \&  Archive::Tar\->create_archive( 'out.tbz', COMPRESS_BZIP, @filelist );
 487 .Ve
 488 .PP
 489 Note that when you pass in a filehandle, the compression argument
 490 is ignored, as all files are printed verbatim to your filehandle.
 491 If you wish to enable compression with filehandles, use an
 492 \&\f(CW\*(C`IO::Zlib\*(C'\fR or \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR filehandle instead.
 493 .PP
 494 The remaining arguments list the files to be included in the tar file.
 495 These files must all exist. Any files which don't exist or can't be
 496 read are silently ignored.
 497 .PP
 498 If the archive creation fails for any reason, \f(CW\*(C`create_archive\*(C'\fR will
 499 return false. Please use the \f(CW\*(C`error\*(C'\fR method to find the cause of the
 500 failure.
 501 .PP
 502 Note that this method does not write \f(CW\*(C`on the fly\*(C'\fR as it were; it
 503 still reads all the files into memory before writing out the archive.
 504 Consult the \s-1FAQ\s0 below if this is a problem.
 505 .ie n .Sh "Archive::Tar\->iter( $filename\fP, [ \f(CW$compressed\fP, {opt => \f(CW$val} ] )"
 506 .el .Sh "Archive::Tar\->iter( \f(CW$filename\fP, [ \f(CW$compressed\fP, {opt => \f(CW$val\fP} ] )"
 507 .IX Subsection "Archive::Tar->iter( $filename, [ $compressed, {opt => $val} ] )"
 508 Returns an iterator function that reads the tar file without loading
 509 it all in memory.  Each time the function is called it will return the
 510 next file in the tarball. The files are returned as
 511 \&\f(CW\*(C`Archive::Tar::File\*(C'\fR objects. The iterator function returns the
 512 empty list once it has exhausted the files contained.
 513 .PP
 514 The second argument can be a hash reference with options, which are
 515 identical to the arguments passed to \f(CW\*(C`read()\*(C'\fR.
 516 .PP
 517 Example usage:
 518 .PP
 519 .Vb 1
 520 \&    my $next = Archive::Tar\->iter( "example.tar.gz", 1, {filter => qr/\e.pm$/} );
 521 .Ve
 522 .PP
 523 .Vb 2
 524 \&    while( my $f = $next\->() ) {
 525 \&        print $f\->name, "\en";
 526 .Ve
 527 .PP
 528 .Vb 1
 529 \&        $f\->extract or warn "Extraction failed";
 530 .Ve
 531 .PP
 532 .Vb 2
 533 \&        # ....
 534 \&    }
 535 .Ve
 536 .ie n .Sh "Archive::Tar\->list_archive($file, $compressed, [\e@properties])"
 537 .el .Sh "Archive::Tar\->list_archive($file, \f(CW$compressed\fP, [\e@properties])"
 538 .IX Subsection "Archive::Tar->list_archive($file, $compressed, [@properties])"
 539 Returns a list of the names of all the files in the archive.  The
 540 first argument can either be the name of the tar file to list or a
 541 reference to an open file handle (e.g. a \s-1GLOB\s0 reference).
 542 .PP
 543 If \f(CW\*(C`list_archive()\*(C'\fR is passed an array reference as its third
 544 argument it returns a list of hash references containing the requested
 545 properties of each file.  The following list of properties is
 546 supported: full_path, name, size, mtime (last modified date), mode,
 547 uid, gid, linkname, uname, gname, devmajor, devminor, prefix.
 548 .PP
 549 See \f(CW\*(C`Archive::Tar::File\*(C'\fR for details about supported properties.
 550 .PP
 551 Passing an array reference containing only one element, 'name', is
 552 special cased to return a list of names rather than a list of hash
 553 references.
 554 .ie n .Sh "Archive::Tar\->extract_archive($file, $compressed)"
 555 .el .Sh "Archive::Tar\->extract_archive($file, \f(CW$compressed\fP)"
 556 .IX Subsection "Archive::Tar->extract_archive($file, $compressed)"
 557 Extracts the contents of the tar file.  The first argument can either
 558 be the name of the tar file to create or a reference to an open file
 559 handle (e.g. a \s-1GLOB\s0 reference).  All relative paths in the tar file will
 560 be created underneath the current working directory.
 561 .PP
 562 \&\f(CW\*(C`extract_archive\*(C'\fR will return a list of files it extracted.
 563 If the archive extraction fails for any reason, \f(CW\*(C`extract_archive\*(C'\fR
 564 will return false.  Please use the \f(CW\*(C`error\*(C'\fR method to find the cause
 565 of the failure.
 566 .Sh "$bool = Archive::Tar\->has_io_string"
 567 .IX Subsection "$bool = Archive::Tar->has_io_string"
 568 Returns true if we currently have \f(CW\*(C`IO::String\*(C'\fR support loaded.
 569 .PP
 570 Either \f(CW\*(C`IO::String\*(C'\fR or \f(CW\*(C`perlio\*(C'\fR support is needed to support writing
 571 stringified archives. Currently, \f(CW\*(C`perlio\*(C'\fR is the preferred method, if
 572 available.
 573 .PP
 574 See the \f(CW\*(C`GLOBAL VARIABLES\*(C'\fR section to see how to change this preference.
 575 .Sh "$bool = Archive::Tar\->has_perlio"
 576 .IX Subsection "$bool = Archive::Tar->has_perlio"
 577 Returns true if we currently have \f(CW\*(C`perlio\*(C'\fR support loaded.
 578 .PP
 579 This requires \f(CW\*(C`perl\-5.8\*(C'\fR or higher, compiled with \f(CW\*(C`perlio\*(C'\fR
 580 .PP
 581 Either \f(CW\*(C`IO::String\*(C'\fR or \f(CW\*(C`perlio\*(C'\fR support is needed to support writing
 582 stringified archives. Currently, \f(CW\*(C`perlio\*(C'\fR is the preferred method, if
 583 available.
 584 .PP
 585 See the \f(CW\*(C`GLOBAL VARIABLES\*(C'\fR section to see how to change this preference.
 586 .Sh "$bool = Archive::Tar\->has_zlib_support"
 587 .IX Subsection "$bool = Archive::Tar->has_zlib_support"
 588 Returns true if \f(CW\*(C`Archive::Tar\*(C'\fR can extract \f(CW\*(C`zlib\*(C'\fR compressed archives
 589 .Sh "$bool = Archive::Tar\->has_bzip2_support"
 590 .IX Subsection "$bool = Archive::Tar->has_bzip2_support"
 591 Returns true if \f(CW\*(C`Archive::Tar\*(C'\fR can extract \f(CW\*(C`bzip2\*(C'\fR compressed archives
 592 .Sh "Archive::Tar\->can_handle_compressed_files"
 593 .IX Subsection "Archive::Tar->can_handle_compressed_files"
 594 A simple checking routine, which will return true if \f(CW\*(C`Archive::Tar\*(C'\fR
 595 is able to uncompress compressed archives on the fly with \f(CW\*(C`IO::Zlib\*(C'\fR
 596 and \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR or false if not both are installed.
 597 .PP
 598 You can use this as a shortcut to determine whether \f(CW\*(C`Archive::Tar\*(C'\fR
 599 will do what you think before passing compressed archives to its
 600 \&\f(CW\*(C`read\*(C'\fR method.
 601 .SH "GLOBAL VARIABLES"
 602 .IX Header "GLOBAL VARIABLES"
 603 .Sh "$Archive::Tar::FOLLOW_SYMLINK"
 604 .IX Subsection "$Archive::Tar::FOLLOW_SYMLINK"
 605 Set this variable to \f(CW1\fR to make \f(CW\*(C`Archive::Tar\*(C'\fR effectively make a
 606 copy of the file when extracting. Default is \f(CW0\fR, which
 607 means the symlink stays intact. Of course, you will have to pack the
 608 file linked to as well.
 609 .PP
 610 This option is checked when you write out the tarfile using \f(CW\*(C`write\*(C'\fR
 611 or \f(CW\*(C`create_archive\*(C'\fR.
 612 .PP
 613 This works just like \f(CW\*(C`/bin/tar\*(C'\fR's \f(CW\*(C`\-h\*(C'\fR option.
 614 .Sh "$Archive::Tar::CHOWN"
 615 .IX Subsection "$Archive::Tar::CHOWN"
 616 By default, \f(CW\*(C`Archive::Tar\*(C'\fR will try to \f(CW\*(C`chown\*(C'\fR your files if it is
 617 able to. In some cases, this may not be desired. In that case, set
 618 this variable to \f(CW0\fR to disable \f(CW\*(C`chown\*(C'\fR\-ing, even if it were
 619 possible.
 620 .PP
 621 The default is \f(CW1\fR.
 622 .Sh "$Archive::Tar::CHMOD"
 623 .IX Subsection "$Archive::Tar::CHMOD"
 624 By default, \f(CW\*(C`Archive::Tar\*(C'\fR will try to \f(CW\*(C`chmod\*(C'\fR your files to
 625 whatever mode was specified for the particular file in the archive.
 626 In some cases, this may not be desired. In that case, set this
 627 variable to \f(CW0\fR to disable \f(CW\*(C`chmod\*(C'\fR\-ing.
 628 .PP
 629 The default is \f(CW1\fR.
 630 .Sh "$Archive::Tar::SAME_PERMISSIONS"
 631 .IX Subsection "$Archive::Tar::SAME_PERMISSIONS"
 632 When, \f(CW$Archive::Tar::CHMOD\fR is enabled, this setting controls whether
 633 the permissions on files from the archive are used without modification
 634 of if they are filtered by removing any setid bits and applying the
 635 current umask.
 636 .PP
 637 The default is \f(CW1\fR for the root user and \f(CW0\fR for normal users.
 638 .Sh "$Archive::Tar::DO_NOT_USE_PREFIX"
 639 .IX Subsection "$Archive::Tar::DO_NOT_USE_PREFIX"
 640 By default, \f(CW\*(C`Archive::Tar\*(C'\fR will try to put paths that are over
 641 100 characters in the \f(CW\*(C`prefix\*(C'\fR field of your tar header, as
 642 defined per POSIX\-standard. However, some (older) tar programs
 643 do not implement this spec. To retain compatibility with these older
 644 or non-POSIX compliant versions, you can set the \f(CW$DO_NOT_USE_PREFIX\fR
 645 variable to a true value, and \f(CW\*(C`Archive::Tar\*(C'\fR will use an alternate
 646 way of dealing with paths over 100 characters by using the
 647 \&\f(CW\*(C`GNU Extended Header\*(C'\fR feature.
 648 .PP
 649 Note that clients who do not support the \f(CW\*(C`GNU Extended Header\*(C'\fR
 650 feature will not be able to read these archives. Such clients include
 651 tars on \f(CW\*(C`Solaris\*(C'\fR, \f(CW\*(C`Irix\*(C'\fR and \f(CW\*(C`AIX\*(C'\fR.
 652 .PP
 653 The default is \f(CW0\fR.
 654 .Sh "$Archive::Tar::DEBUG"
 655 .IX Subsection "$Archive::Tar::DEBUG"
 656 Set this variable to \f(CW1\fR to always get the \f(CW\*(C`Carp::longmess\*(C'\fR output
 657 of the warnings, instead of the regular \f(CW\*(C`carp\*(C'\fR. This is the same
 658 message you would get by doing:
 659 .PP
 660 .Vb 1
 661 \&    $tar\->error(1);
 662 .Ve
 663 .PP
 664 Defaults to \f(CW0\fR.
 665 .Sh "$Archive::Tar::WARN"
 666 .IX Subsection "$Archive::Tar::WARN"
 667 Set this variable to \f(CW0\fR if you do not want any warnings printed.
 668 Personally I recommend against doing this, but people asked for the
 669 option. Also, be advised that this is of course not threadsafe.
 670 .PP
 671 Defaults to \f(CW1\fR.
 672 .Sh "$Archive::Tar::error"
 673 .IX Subsection "$Archive::Tar::error"
 674 Holds the last reported error. Kept for historical reasons, but its
 675 use is very much discouraged. Use the \f(CW\*(C`error()\*(C'\fR method instead:
 676 .PP
 677 .Vb 1
 678 \&    warn $tar\->error unless $tar\->extract;
 679 .Ve
 680 .PP
 681 Note that in older versions of this module, the \f(CW\*(C`error()\*(C'\fR method
 682 would return an effectively global value even when called an instance
 683 method as above. This has since been fixed, and multiple instances of
 684 \&\f(CW\*(C`Archive::Tar\*(C'\fR now have separate error strings.
 685 .Sh "$Archive::Tar::INSECURE_EXTRACT_MODE"
 686 .IX Subsection "$Archive::Tar::INSECURE_EXTRACT_MODE"
 687 This variable indicates whether \f(CW\*(C`Archive::Tar\*(C'\fR should allow
 688 files to be extracted outside their current working directory.
 689 .PP
 690 Allowing this could have security implications, as a malicious
 691 tar archive could alter or replace any file the extracting user
 692 has permissions to. Therefor, the default is to not allow
 693 insecure extractions.
 694 .PP
 695 If you trust the archive, or have other reasons to allow the
 696 archive to write files outside your current working directory,
 697 set this variable to \f(CW\*(C`true\*(C'\fR.
 698 .PP
 699 Note that this is a backwards incompatible change from version
 700 \&\f(CW1.36\fR and before.
 701 .Sh "$Archive::Tar::HAS_PERLIO"
 702 .IX Subsection "$Archive::Tar::HAS_PERLIO"
 703 This variable holds a boolean indicating if we currently have
 704 \&\f(CW\*(C`perlio\*(C'\fR support loaded. This will be enabled for any perl
 705 greater than \f(CW5.8\fR compiled with \f(CW\*(C`perlio\*(C'\fR.
 706 .PP
 707 If you feel strongly about disabling it, set this variable to
 708 \&\f(CW\*(C`false\*(C'\fR. Note that you will then need \f(CW\*(C`IO::String\*(C'\fR installed
 709 to support writing stringified archives.
 710 .PP
 711 Don't change this variable unless you \fBreally\fR know what you're
 712 doing.
 713 .Sh "$Archive::Tar::HAS_IO_STRING"
 714 .IX Subsection "$Archive::Tar::HAS_IO_STRING"
 715 This variable holds a boolean indicating if we currently have
 716 \&\f(CW\*(C`IO::String\*(C'\fR support loaded. This will be enabled for any perl
 717 that has a loadable \f(CW\*(C`IO::String\*(C'\fR module.
 718 .PP
 719 If you feel strongly about disabling it, set this variable to
 720 \&\f(CW\*(C`false\*(C'\fR. Note that you will then need \f(CW\*(C`perlio\*(C'\fR support from
 721 your perl to be able to  write stringified archives.
 722 .PP
 723 Don't change this variable unless you \fBreally\fR know what you're
 724 doing.
 725 .SH "FAQ"
 726 .IX Header "FAQ"
 727 .IP "What's the minimum perl version required to run Archive::Tar?" 4
 728 .IX Item "What's the minimum perl version required to run Archive::Tar?"
 729 You will need perl version 5.005_03 or newer.
 730 .IP "Isn't Archive::Tar slow?" 4
 731 .IX Item "Isn't Archive::Tar slow?"
 732 Yes it is. It's pure perl, so it's a lot slower then your \f(CW\*(C`/bin/tar\*(C'\fR
 733 However, it's very portable. If speed is an issue, consider using
 734 \&\f(CW\*(C`/bin/tar\*(C'\fR instead.
 735 .IP "Isn't Archive::Tar heavier on memory than /bin/tar?" 4
 736 .IX Item "Isn't Archive::Tar heavier on memory than /bin/tar?"
 737 Yes it is, see previous answer. Since \f(CW\*(C`Compress::Zlib\*(C'\fR and therefore
 738 \&\f(CW\*(C`IO::Zlib\*(C'\fR doesn't support \f(CW\*(C`seek\*(C'\fR on their filehandles, there is little
 739 choice but to read the archive into memory.
 740 This is ok if you want to do in-memory manipulation of the archive.
 741 .Sp
 742 If you just want to extract, use the \f(CW\*(C`extract_archive\*(C'\fR class method
 743 instead. It will optimize and write to disk immediately.
 744 .Sp
 745 Another option is to use the \f(CW\*(C`iter\*(C'\fR class method to iterate over
 746 the files in the tarball without reading them all in memory at once.
 747 .IP "Can you lazy-load data instead?" 4
 748 .IX Item "Can you lazy-load data instead?"
 749 In some cases, yes. You can use the \f(CW\*(C`iter\*(C'\fR class method to iterate
 750 over the files in the tarball without reading them all in memory at once.
 751 .IP "How much memory will an X kb tar file need?" 4
 752 .IX Item "How much memory will an X kb tar file need?"
 753 Probably more than X kb, since it will all be read into memory. If
 754 this is a problem, and you don't need to do in memory manipulation
 755 of the archive, consider using the \f(CW\*(C`iter\*(C'\fR class method, or \f(CW\*(C`/bin/tar\*(C'\fR
 756 instead.
 757 .IP "What do you do with unsupported filetypes in an archive?" 4
 758 .IX Item "What do you do with unsupported filetypes in an archive?"
 759 \&\f(CW\*(C`Unix\*(C'\fR has a few filetypes that aren't supported on other platforms,
 760 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
 761 try to make a copy of the original file, rather than throwing an error.
 762 .Sp
 763 This does require you to read the entire archive in to memory first,
 764 since otherwise we wouldn't know what data to fill the copy with.
 765 (This means that you cannot use the class methods, including \f(CW\*(C`iter\*(C'\fR
 766 on archives that have incompatible filetypes and still expect things
 767 to work).
 768 .Sp
 769 For other filetypes, like \f(CW\*(C`chardevs\*(C'\fR and \f(CW\*(C`blockdevs\*(C'\fR we'll warn that
 770 the extraction of this particular item didn't work.
 771 .IP "I'm using WinZip, or some other non-POSIX client, and files are not being extracted properly!" 4
 772 .IX Item "I'm using WinZip, or some other non-POSIX client, and files are not being extracted properly!"
 773 By default, \f(CW\*(C`Archive::Tar\*(C'\fR is in a completely POSIX-compatible
 774 mode, which uses the POSIX-specification of \f(CW\*(C`tar\*(C'\fR to store files.
 775 For paths greather than 100 characters, this is done using the
 776 \&\f(CW\*(C`POSIX header prefix\*(C'\fR. Non-POSIX-compatible clients may not support
 777 this part of the specification, and may only support the \f(CW\*(C`GNU Extended
 778 Header\*(C'\fR functionality. To facilitate those clients, you can set the
 779 \&\f(CW$Archive::Tar::DO_NOT_USE_PREFIX\fR variable to \f(CW\*(C`true\*(C'\fR. See the
 780 \&\f(CW\*(C`GLOBAL VARIABLES\*(C'\fR section for details on this variable.
 781 .Sp
 782 Note that \s-1GNU\s0 tar earlier than version 1.14 does not cope well with
 783 the \f(CW\*(C`POSIX header prefix\*(C'\fR. If you use such a version, consider setting
 784 the \f(CW$Archive::Tar::DO_NOT_USE_PREFIX\fR variable to \f(CW\*(C`true\*(C'\fR.
 785 .IP "How do I extract only files that have property X from an archive?" 4
 786 .IX Item "How do I extract only files that have property X from an archive?"
 787 Sometimes, you might not wish to extract a complete archive, just
 788 the files that are relevant to you, based on some criteria.
 789 .Sp
 790 You can do this by filtering a list of \f(CW\*(C`Archive::Tar::File\*(C'\fR objects
 791 based on your criteria. For example, to extract only files that have
 792 the string \f(CW\*(C`foo\*(C'\fR in their title, you would use:
 793 .Sp
 794 .Vb 3
 795 \&    $tar\->extract(
 796 \&        grep { $_\->full_path =~ /foo/ } $tar\->get_files
 797 \&    );
 798 .Ve
 799 .Sp
 800 This way, you can filter on any attribute of the files in the archive.
 801 Consult the \f(CW\*(C`Archive::Tar::File\*(C'\fR documentation on how to use these
 802 objects.
 803 .IP "How do I access .tar.Z files?" 4
 804 .IX Item "How do I access .tar.Z files?"
 805 The \f(CW\*(C`Archive::Tar\*(C'\fR module can optionally use \f(CW\*(C`Compress::Zlib\*(C'\fR (via
 806 the \f(CW\*(C`IO::Zlib\*(C'\fR module) to access tar files that have been compressed
 807 with \f(CW\*(C`gzip\*(C'\fR. Unfortunately tar files compressed with the Unix \f(CW\*(C`compress\*(C'\fR
 808 utility cannot be read by \f(CW\*(C`Compress::Zlib\*(C'\fR and so cannot be directly
 809 accesses by \f(CW\*(C`Archive::Tar\*(C'\fR.
 810 .Sp
 811 If the \f(CW\*(C`uncompress\*(C'\fR or \f(CW\*(C`gunzip\*(C'\fR programs are available, you can use
 812 one of these workarounds to read \f(CW\*(C`.tar.Z\*(C'\fR files from \f(CW\*(C`Archive::Tar\*(C'\fR
 813 .Sp
 814 Firstly with \f(CW\*(C`uncompress\*(C'\fR
 815 .Sp
 816 .Vb 1
 817 \&    use Archive::Tar;
 818 .Ve
 819 .Sp
 820 .Vb 3
 821 \&    open F, "uncompress \-c $filename |";
 822 \&    my $tar = Archive::Tar\->new(*F);
 823 \&    ...
 824 .Ve
 825 .Sp
 826 and this with \f(CW\*(C`gunzip\*(C'\fR
 827 .Sp
 828 .Vb 1
 829 \&    use Archive::Tar;
 830 .Ve
 831 .Sp
 832 .Vb 3
 833 \&    open F, "gunzip \-c $filename |";
 834 \&    my $tar = Archive::Tar\->new(*F);
 835 \&    ...
 836 .Ve
 837 .Sp
 838 Similarly, if the \f(CW\*(C`compress\*(C'\fR program is available, you can use this to
 839 write a \f(CW\*(C`.tar.Z\*(C'\fR file
 840 .Sp
 841 .Vb 2
 842 \&    use Archive::Tar;
 843 \&    use IO::File;
 844 .Ve
 845 .Sp
 846 .Vb 5
 847 \&    my $fh = new IO::File "| compress \-c >$filename";
 848 \&    my $tar = Archive::Tar\->new();
 849 \&    ...
 850 \&    $tar\->write($fh);
 851 \&    $fh\->close ;
 852 .Ve
 853 .IP "How do I handle Unicode strings?" 4
 854 .IX Item "How do I handle Unicode strings?"
 855 \&\f(CW\*(C`Archive::Tar\*(C'\fR uses byte semantics for any files it reads from or writes
 856 to disk. This is not a problem if you only deal with files and never
 857 look at their content or work solely with byte strings. But if you use
 858 Unicode strings with character semantics, some additional steps need
 859 to be taken.
 860 .Sp
 861 For example, if you add a Unicode string like
 862 .Sp
 863 .Vb 2
 864 \&    # Problem
 865 \&    $tar\->add_data('file.txt', "Euro: \ex{20AC}");
 866 .Ve
 867 .Sp
 868 then there will be a problem later when the tarfile gets written out
 869 to disk via \f(CW\*(C`$tar\-\*(C'\fR\fIwrite()\fR>:
 870 .Sp
 871 .Vb 1
 872 \&    Wide character in print at .../Archive/Tar.pm line 1014.
 873 .Ve
 874 .Sp
 875 The data was added as a Unicode string and when writing it out to disk,
 876 the \f(CW\*(C`:utf8\*(C'\fR line discipline wasn't set by \f(CW\*(C`Archive::Tar\*(C'\fR, so Perl
 877 tried to convert the string to \s-1ISO\-8859\s0 and failed. The written file
 878 now contains garbage.
 879 .Sp
 880 For this reason, Unicode strings need to be converted to UTF\-8\-encoded
 881 bytestrings before they are handed off to \f(CW\*(C`add_data()\*(C'\fR:
 882 .Sp
 883 .Vb 3
 884 \&    use Encode;
 885 \&    my $data = "Accented character: \ex{20AC}";
 886 \&    $data = encode('utf8', $data);
 887 .Ve
 888 .Sp
 889 .Vb 1
 890 \&    $tar\->add_data('file.txt', $data);
 891 .Ve
 892 .Sp
 893 A opposite problem occurs if you extract a UTF8\-encoded file from a
 894 tarball. Using \f(CW\*(C`get_content()\*(C'\fR on the \f(CW\*(C`Archive::Tar::File\*(C'\fR object
 895 will return its content as a bytestring, not as a Unicode string.
 896 .Sp
 897 If you want it to be a Unicode string (because you want character
 898 semantics with operations like regular expression matching), you need
 899 to decode the UTF8\-encoded content and have Perl convert it into
 900 a Unicode string:
 901 .Sp
 902 .Vb 2
 903 \&    use Encode;
 904 \&    my $data = $tar\->get_content();
 905 .Ve
 906 .Sp
 907 .Vb 2
 908 \&    # Make it a Unicode string
 909 \&    $data = decode('utf8', $data);
 910 .Ve
 911 .Sp
 912 There is no easy way to provide this functionality in \f(CW\*(C`Archive::Tar\*(C'\fR,
 913 because a tarball can contain many files, and each of which could be
 914 encoded in a different way.
 915 .SH "CAVEATS"
 916 .IX Header "CAVEATS"
 917 The \s-1AIX\s0 tar does not fill all unused space in the tar archive with 0x00.
 918 This sometimes leads to warning messages from \f(CW\*(C`Archive::Tar\*(C'\fR.
 919 .PP
 920 .Vb 1
 921 \&  Invalid header block at offset nnn
 922 .Ve
 923 .PP
 924 A fix for that problem is scheduled to be released in the following levels
 925 of \s-1AIX\s0, all of which should be coming out in the 4th quarter of 2009:
 926 .PP
 927 .Vb 4
 928 \& AIX 5.3 TL7 SP10
 929 \& AIX 5.3 TL8 SP8
 930 \& AIX 5.3 TL9 SP5
 931 \& AIX 5.3 TL10 SP2
 932 .Ve
 933 .PP
 934 .Vb 4
 935 \& AIX 6.1 TL0 SP11
 936 \& AIX 6.1 TL1 SP7
 937 \& AIX 6.1 TL2 SP6
 938 \& AIX 6.1 TL3 SP3
 939 .Ve
 940 .PP
 941 The \s-1IBM\s0 \s-1APAR\s0 number for this problem is \s-1IZ50240\s0 (Reported component \s-1ID:\s0
 942 5765G0300 / \s-1AIX\s0 5.3). It is possible to get an ifix for that problem.
 943 If you need an ifix please contact your local \s-1IBM\s0 \s-1AIX\s0 support.
 944 .SH "TODO"
 945 .IX Header "TODO"
 946 .IP "Check if passed in handles are open for read/write" 4
 947 .IX Item "Check if passed in handles are open for read/write"
 948 Currently I don't know of any portable pure perl way to do this.
 949 Suggestions welcome.
 950 .IP "Allow archives to be passed in as string" 4
 951 .IX Item "Allow archives to be passed in as string"
 952 Currently, we only allow opened filehandles or filenames, but
 953 not strings. The internals would need some reworking to facilitate
 954 stringified archives.
 955 .IP "Facilitate processing an opened filehandle of a compressed archive" 4
 956 .IX Item "Facilitate processing an opened filehandle of a compressed archive"
 957 Currently, we only support this if the filehandle is an IO::Zlib object.
 958 Environments, like apache, will present you with an opened filehandle
 959 to an uploaded file, which might be a compressed archive.
 960 .SH "SEE ALSO"
 961 .IX Header "SEE ALSO"
 962 .IP "The \s-1GNU\s0 tar specification" 4
 963 .IX Item "The GNU tar specification"
 964 \&\f(CW\*(C`http://www.gnu.org/software/tar/manual/tar.html\*(C'\fR
 965 .IP "The \s-1PAX\s0 format specication" 4
 966 .IX Item "The PAX format specication"
 967 The specifcation which tar derives from; \f(CW\*(C` http://www.opengroup.org/onlinepubs/007904975/utilities/pax.html\*(C'\fR
 968 .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
 969 .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
 970 .IX Item "A comparison of GNU and POSIX tar standards; http://www.delorie.com/gnu/docs/tar/tar_114.html"
 971 .PD 0
 972 .IP "\s-1GNU\s0 tar intends to switch to \s-1POSIX\s0 compatibility" 4
 973 .IX Item "GNU tar intends to switch to POSIX compatibility"
 974 .PD
 975 \&\s-1GNU\s0 Tar authors have expressed their intention to become completely
 976 POSIX\-compatible; \f(CW\*(C`http://www.gnu.org/software/tar/manual/html_node/Formats.html\*(C'\fR
 977 .IP "A Comparison between various tar implementations" 4
 978 .IX Item "A Comparison between various tar implementations"
 979 Lists known issues and incompatibilities; \f(CW\*(C`http://gd.tuwien.ac.at/utils/archivers/star/README.otherbugs\*(C'\fR
 980 .SH "AUTHOR"
 981 .IX Header "AUTHOR"
 982 This module by Jos Boumans <kane@cpan.org>.
 983 .PP
 984 Please reports bugs to <bug\-archive\-tar@rt.cpan.org>.
 985 .SH "ACKNOWLEDGEMENTS"
 986 .IX Header "ACKNOWLEDGEMENTS"
 987 Thanks to Sean Burke, Chris Nandor, Chip Salzenberg, Tim Heaney, Gisle Aas,
 988 Rainer Tammer and especially Andrew Savige for their help and suggestions.
 989 .SH "COPYRIGHT"
 990 .IX Header "COPYRIGHT"
 991 This module is copyright (c) 2002 \- 2009 Jos Boumans
 992 <kane@cpan.org>. All rights reserved.
 993 .PP
 994 This library is free software; you may redistribute and/or modify
 995 it under the same terms as Perl itself.