1Archive::Tar(3pm) Perl Programmers Reference Guide Archive::Tar(3pm)
2
6 Archive::Tar - module for manipulations of tar archives
7
9 use Archive::Tar;
10 my $tar = Archive::Tar->new;
11 $tar->read('origin.tgz');
13 $tar->extract();
14 $tar->add_files('file/foo.pl', 'docs/README');
16 $tar->add_data('file/baz.txt', 'This is the contents now');
17 $tar->rename('oldname', 'new/file/name');
19 $tar->write('files.tar'); # plain tar
21 $tar->write('files.tgz', COMPRESS_GZIP); # gzip compressed
22 $tar->write('files.tbz', COMPRESS_BZIP); # bzip2 compressed
23
25 Archive::Tar provides an object oriented mechanism for handling tar
26 files. It provides class methods for quick and easy files handling
27 while also allowing for the creation of tar file objects for custom
28 manipulation. If you have the IO::Zlib module installed, Archive::Tar
29 will also support compressed or gzipped tar files.
30 An object of class Archive::Tar represents a .tar(.gz) archive full of
32 files and things.
33
35 Archive::Tar->new( [$file, $compressed] )
36 Returns a new Tar object. If given any arguments, "new()" calls the
37 "read()" method automatically, passing on the arguments provided to the
38 "read()" method.
39 If "new()" is invoked with arguments and the "read()" method fails for
41 any reason, "new()" returns undef.
42 $tar->read ( $filename|$handle, [$compressed, {opt => 'val'}] )
44 Read the given tar file into memory. The first argument can either be
45 the name of a file or a reference to an already open filehandle (or an
46 IO::Zlib object if it's compressed)
47 The "read" will replace any previous content in $tar!
49 The second argument may be considered optional, but remains for
51 backwards compatibility. Archive::Tar now looks at the file magic to
52 determine what class should be used to open the file and will
53 transparently Do The Right Thing.
54 Archive::Tar will warn if you try to pass a bzip2 compressed file and
56 the IO::Zlib / IO::Uncompress::Bunzip2 modules are not available and
57 simply return.
58 Note that you can currently not pass a "gzip" compressed filehandle,
60 which is not opened with "IO::Zlib", a "bzip2" compressed filehandle,
61 which is not opened with "IO::Uncompress::Bunzip2", nor a string
62 containing the full archive information (either compressed or
63 uncompressed). These are worth while features, but not currently
64 implemented. See the "TODO" section.
65 The third argument can be a hash reference with options. Note that all
67 options are case-sensitive.
68 limit
70 Do not read more than "limit" files. This is useful if you have
71 very big archives, and are only interested in the first few files.
72 filter
74 Can be set to a regular expression. Only files with names that
75 match the expression will be read.
76 extract
78 If set to true, immediately extract entries when reading them. This
79 gives you the same memory break as the "extract_archive" function.
80 Note however that entries will not be read into memory, but written
81 straight to disk. This means no "Archive::Tar::File" objects are
82 created for you to inspect.
83 All files are stored internally as "Archive::Tar::File" objects.
85 Please consult the Archive::Tar::File documentation for details.
86 Returns the number of files read in scalar context, and a list of
88 "Archive::Tar::File" objects in list context.
89 $tar->contains_file( $filename )
91 Check if the archive contains a certain file. It will return true if
92 the file is in the archive, false otherwise.
93 Note however, that this function does an exact match using "eq" on the
95 full path. So it cannot compensate for case-insensitive file- systems
96 or compare 2 paths to see if they would point to the same underlying
97 file.
98 $tar->extract( [@filenames] )
100 Write files whose names are equivalent to any of the names in
101 @filenames to disk, creating subdirectories as necessary. This might
102 not work too well under VMS. Under MacPerl, the file's modification
103 time will be converted to the MacOS zero of time, and appropriate
104 conversions will be done to the path. However, the length of each
105 element of the path is not inspected to see whether it's longer than
106 MacOS currently allows (32 characters).
107 If "extract" is called without a list of file names, the entire
109 contents of the archive are extracted.
110 Returns a list of filenames extracted.
112 $tar->extract_file( $file, [$extract_path] )
114 Write an entry, whose name is equivalent to the file name provided to
115 disk. Optionally takes a second parameter, which is the full native
116 path (including filename) the entry will be written to.
117 For example:
119 $tar->extract_file( 'name/in/archive', 'name/i/want/to/give/it' );
121 $tar->extract_file( $at_file_object, 'name/i/want/to/give/it' );
123 Returns true on success, false on failure.
125 $tar->list_files( [\@properties] )
127 Returns a list of the names of all the files in the archive.
128 If "list_files()" is passed an array reference as its first argument it
130 returns a list of hash references containing the requested properties
131 of each file. The following list of properties is supported: name,
132 size, mtime (last modified date), mode, uid, gid, linkname, uname,
133 gname, devmajor, devminor, prefix.
134 Passing an array reference containing only one element, 'name', is
136 special cased to return a list of names rather than a list of hash
137 references, making it equivalent to calling "list_files" without
138 arguments.
139 $tar->get_files( [@filenames] )
141 Returns the "Archive::Tar::File" objects matching the filenames
142 provided. If no filename list was passed, all "Archive::Tar::File"
143 objects in the current Tar object are returned.
144 Please refer to the "Archive::Tar::File" documentation on how to handle
146 these objects.
147 $tar->get_content( $file )
149 Return the content of the named file.
150 $tar->replace_content( $file, $content )
152 Make the string $content be the content for the file named $file.
153 $tar->rename( $file, $new_name )
155 Rename the file of the in-memory archive to $new_name.
156 Note that you must specify a Unix path for $new_name, since per tar
158 standard, all files in the archive must be Unix paths.
159 Returns true on success and false on failure.
161 $tar->remove (@filenamelist)
163 Removes any entries with names matching any of the given filenames from
164 the in-memory archive. Returns a list of "Archive::Tar::File" objects
165 that remain.
166 $tar->clear
168 "clear" clears the current in-memory archive. This effectively gives
169 you a 'blank' object, ready to be filled again. Note that "clear" only
170 has effect on the object, not the underlying tarfile.
171 $tar->write ( [$file, $compressed, $prefix] )
173 Write the in-memory archive to disk. The first argument can either be
174 the name of a file or a reference to an already open filehandle (a GLOB
175 reference).
176 The second argument is used to indicate compression. You can either
178 compress using "gzip" or "bzip2". If you pass a digit, it's assumed to
179 be the "gzip" compression level (between 1 and 9), but the use of
180 constants is prefered:
181 # write a gzip compressed file
183 $tar->write( 'out.tgz', COMPRESS_GZIP );
184 # write a bzip compressed file
186 $tar->write( 'out.tbz', COMPRESS_BZIP );
187 Note that when you pass in a filehandle, the compression argument is
189 ignored, as all files are printed verbatim to your filehandle. If you
190 wish to enable compression with filehandles, use an "IO::Zlib" or
191 "IO::Compress::Bzip2" filehandle instead.
192 The third argument is an optional prefix. All files will be tucked away
194 in the directory you specify as prefix. So if you have files 'a' and
195 'b' in your archive, and you specify 'foo' as prefix, they will be
196 written to the archive as 'foo/a' and 'foo/b'.
197 If no arguments are given, "write" returns the entire formatted archive
199 as a string, which could be useful if you'd like to stuff the archive
200 into a socket or a pipe to gzip or something.
201 $tar->add_files( @filenamelist )
203 Takes a list of filenames and adds them to the in-memory archive.
204 The path to the file is automatically converted to a Unix like
206 equivalent for use in the archive, and, if on MacOS, the file's
207 modification time is converted from the MacOS epoch to the Unix epoch.
208 So tar archives created on MacOS with Archive::Tar can be read both
209 with tar on Unix and applications like suntar or Stuffit Expander on
210 MacOS.
211 Be aware that the file's type/creator and resource fork will be lost,
213 which is usually what you want in cross-platform archives.
214 Instead of a filename, you can also pass it an existing
216 "Archive::Tar::File" object from, for example, another archive. The
217 object will be clone, and effectively be a copy of the original, not an
218 alias.
219 Returns a list of "Archive::Tar::File" objects that were just added.
221 $tar->add_data ( $filename, $data, [$opthashref] )
223 Takes a filename, a scalar full of data and optionally a reference to a
224 hash with specific options.
225 Will add a file to the in-memory archive, with name $filename and
227 content $data. Specific properties can be set using $opthashref. The
228 following list of properties is supported: name, size, mtime (last
229 modified date), mode, uid, gid, linkname, uname, gname, devmajor,
230 devminor, prefix, type. (On MacOS, the file's path and modification
231 times are converted to Unix equivalents.)
232 Valid values for the file type are the following constants defined in
234 Archive::Tar::Constants:
235 FILE
237 Regular file.
238 HARDLINK
240 SYMLINK
241 Hard and symbolic ("soft") links; linkname should specify target.
242 CHARDEV
244 BLOCKDEV
245 Character and block devices. devmajor and devminor should specify
246 the major and minor device numbers.
247 DIR Directory.
249 FIFO
251 FIFO (named pipe).
252 SOCKET
254 Socket.
255 Returns the "Archive::Tar::File" object that was just added, or "undef"
257 on failure.
258 $tar->error( [$BOOL] )
260 Returns the current errorstring (usually, the last error reported). If
261 a true value was specified, it will give the "Carp::longmess"
262 equivalent of the error, in effect giving you a stacktrace.
263 For backwards compatibility, this error is also available as
265 $Archive::Tar::error although it is much recommended you use the method
266 call instead.
267 $tar->setcwd( $cwd );
269 "Archive::Tar" needs to know the current directory, and it will run
270 "Cwd::cwd()" every time it extracts a relative entry from the tarfile
271 and saves it in the file system. (As of version 1.30, however,
272 "Archive::Tar" will use the speed optimization described below
273 automatically, so it's only relevant if you're using "extract_file()").
274 Since "Archive::Tar" doesn't change the current directory internally
276 while it is extracting the items in a tarball, all calls to
277 "Cwd::cwd()" can be avoided if we can guarantee that the current
278 directory doesn't get changed externally.
279 To use this performance boost, set the current directory via
281 use Cwd;
283 $tar->setcwd( cwd() );
284 once before calling a function like "extract_file" and "Archive::Tar"
286 will use the current directory setting from then on and won't call
287 "Cwd::cwd()" internally.
288 To switch back to the default behaviour, use
290 $tar->setcwd( undef );
292 and "Archive::Tar" will call "Cwd::cwd()" internally again.
294 If you're using "Archive::Tar"'s "exract()" method, "setcwd()" will be
296 called for you.
297
299 Archive::Tar->create_archive($file, $compressed, @filelist)
300 Creates a tar file from the list of files provided. The first argument
301 can either be the name of the tar file to create or a reference to an
302 open file handle (e.g. a GLOB reference).
303 The second argument is used to indicate compression. You can either
305 compress using "gzip" or "bzip2". If you pass a digit, it's assumed to
306 be the "gzip" compression level (between 1 and 9), but the use of
307 constants is prefered:
308 # write a gzip compressed file
310 Archive::Tar->create_archive( 'out.tgz', COMPRESS_GZIP, @filelist );
311 # write a bzip compressed file
313 Archive::Tar->create_archive( 'out.tbz', COMPRESS_BZIP, @filelist );
314 Note that when you pass in a filehandle, the compression argument is
316 ignored, as all files are printed verbatim to your filehandle. If you
317 wish to enable compression with filehandles, use an "IO::Zlib" or
318 "IO::Compress::Bzip2" filehandle instead.
319 The remaining arguments list the files to be included in the tar file.
321 These files must all exist. Any files which don't exist or can't be
322 read are silently ignored.
323 If the archive creation fails for any reason, "create_archive" will
325 return false. Please use the "error" method to find the cause of the
326 failure.
327 Note that this method does not write "on the fly" as it were; it still
329 reads all the files into memory before writing out the archive.
330 Consult the FAQ below if this is a problem.
331 Archive::Tar->iter( $filename, [ $compressed, {opt => $val} ] )
333 Returns an iterator function that reads the tar file without loading it
334 all in memory. Each time the function is called it will return the
335 next file in the tarball. The files are returned as
336 "Archive::Tar::File" objects. The iterator function returns the empty
337 list once it has exhausted the files contained.
338 The second argument can be a hash reference with options, which are
340 identical to the arguments passed to "read()".
341 Example usage:
343 my $next = Archive::Tar->iter( "example.tar.gz", 1, {filter => qr/\.pm$/} );
345 while( my $f = $next->() ) {
347 print $f->name, "\n";
348 $f->extract or warn "Extraction failed";
350 # ....
352 }
353 Archive::Tar->list_archive($file, $compressed, [\@properties])
355 Returns a list of the names of all the files in the archive. The first
356 argument can either be the name of the tar file to list or a reference
357 to an open file handle (e.g. a GLOB reference).
358 If "list_archive()" is passed an array reference as its third argument
360 it returns a list of hash references containing the requested
361 properties of each file. The following list of properties is
362 supported: full_path, name, size, mtime (last modified date), mode,
363 uid, gid, linkname, uname, gname, devmajor, devminor, prefix.
364 See "Archive::Tar::File" for details about supported properties.
366 Passing an array reference containing only one element, 'name', is
368 special cased to return a list of names rather than a list of hash
369 references.
370 Archive::Tar->extract_archive($file, $compressed)
372 Extracts the contents of the tar file. The first argument can either
373 be the name of the tar file to create or a reference to an open file
374 handle (e.g. a GLOB reference). All relative paths in the tar file
375 will be created underneath the current working directory.
376 "extract_archive" will return a list of files it extracted. If the
378 archive extraction fails for any reason, "extract_archive" will return
379 false. Please use the "error" method to find the cause of the failure.
380 $bool = Archive::Tar->has_io_string
382 Returns true if we currently have "IO::String" support loaded.
383 Either "IO::String" or "perlio" support is needed to support writing
385 stringified archives. Currently, "perlio" is the preferred method, if
386 available.
387 See the "GLOBAL VARIABLES" section to see how to change this
389 preference.
390 $bool = Archive::Tar->has_perlio
392 Returns true if we currently have "perlio" support loaded.
393 This requires "perl-5.8" or higher, compiled with "perlio"
395 Either "IO::String" or "perlio" support is needed to support writing
397 stringified archives. Currently, "perlio" is the preferred method, if
398 available.
399 See the "GLOBAL VARIABLES" section to see how to change this
401 preference.
402 $bool = Archive::Tar->has_zlib_support
404 Returns true if "Archive::Tar" can extract "zlib" compressed archives
405 $bool = Archive::Tar->has_bzip2_support
407 Returns true if "Archive::Tar" can extract "bzip2" compressed archives
408 Archive::Tar->can_handle_compressed_files
410 A simple checking routine, which will return true if "Archive::Tar" is
411 able to uncompress compressed archives on the fly with "IO::Zlib" and
412 "IO::Compress::Bzip2" or false if not both are installed.
413 You can use this as a shortcut to determine whether "Archive::Tar" will
415 do what you think before passing compressed archives to its "read"
416 method.
417
419 $Archive::Tar::FOLLOW_SYMLINK
420 Set this variable to 1 to make "Archive::Tar" effectively make a copy
421 of the file when extracting. Default is 0, which means the symlink
422 stays intact. Of course, you will have to pack the file linked to as
423 well.
424 This option is checked when you write out the tarfile using "write" or
426 "create_archive".
427 This works just like "/bin/tar"'s "-h" option.
429 $Archive::Tar::CHOWN
431 By default, "Archive::Tar" will try to "chown" your files if it is able
432 to. In some cases, this may not be desired. In that case, set this
433 variable to 0 to disable "chown"-ing, even if it were possible.
434 The default is 1.
436 $Archive::Tar::CHMOD
438 By default, "Archive::Tar" will try to "chmod" your files to whatever
439 mode was specified for the particular file in the archive. In some
440 cases, this may not be desired. In that case, set this variable to 0 to
441 disable "chmod"-ing.
442 The default is 1.
444 $Archive::Tar::SAME_PERMISSIONS
446 When, $Archive::Tar::CHMOD is enabled, this setting controls whether
447 the permissions on files from the archive are used without modification
448 of if they are filtered by removing any setid bits and applying the
449 current umask.
450 The default is 1 for the root user and 0 for normal users.
452 $Archive::Tar::DO_NOT_USE_PREFIX
454 By default, "Archive::Tar" will try to put paths that are over 100
455 characters in the "prefix" field of your tar header, as defined per
456 POSIX-standard. However, some (older) tar programs do not implement
457 this spec. To retain compatibility with these older or non-POSIX
458 compliant versions, you can set the $DO_NOT_USE_PREFIX variable to a
459 true value, and "Archive::Tar" will use an alternate way of dealing
460 with paths over 100 characters by using the "GNU Extended Header"
461 feature.
462 Note that clients who do not support the "GNU Extended Header" feature
464 will not be able to read these archives. Such clients include tars on
465 "Solaris", "Irix" and "AIX".
466 The default is 0.
468 $Archive::Tar::DEBUG
470 Set this variable to 1 to always get the "Carp::longmess" output of the
471 warnings, instead of the regular "carp". This is the same message you
472 would get by doing:
473 $tar->error(1);
475 Defaults to 0.
477 $Archive::Tar::WARN
479 Set this variable to 0 if you do not want any warnings printed.
480 Personally I recommend against doing this, but people asked for the
481 option. Also, be advised that this is of course not threadsafe.
482 Defaults to 1.
484 $Archive::Tar::error
486 Holds the last reported error. Kept for historical reasons, but its use
487 is very much discouraged. Use the "error()" method instead:
488 warn $tar->error unless $tar->extract;
490 Note that in older versions of this module, the "error()" method would
492 return an effectively global value even when called an instance method
493 as above. This has since been fixed, and multiple instances of
494 "Archive::Tar" now have separate error strings.
495 $Archive::Tar::INSECURE_EXTRACT_MODE
497 This variable indicates whether "Archive::Tar" should allow files to be
498 extracted outside their current working directory.
499 Allowing this could have security implications, as a malicious tar
501 archive could alter or replace any file the extracting user has
502 permissions to. Therefor, the default is to not allow insecure
503 extractions.
504 If you trust the archive, or have other reasons to allow the archive to
506 write files outside your current working directory, set this variable
507 to "true".
508 Note that this is a backwards incompatible change from version 1.36 and
510 before.
511 $Archive::Tar::HAS_PERLIO
513 This variable holds a boolean indicating if we currently have "perlio"
514 support loaded. This will be enabled for any perl greater than 5.8
515 compiled with "perlio".
516 If you feel strongly about disabling it, set this variable to "false".
518 Note that you will then need "IO::String" installed to support writing
519 stringified archives.
520 Don't change this variable unless you really know what you're doing.
522 $Archive::Tar::HAS_IO_STRING
524 This variable holds a boolean indicating if we currently have
525 "IO::String" support loaded. This will be enabled for any perl that has
526 a loadable "IO::String" module.
527 If you feel strongly about disabling it, set this variable to "false".
529 Note that you will then need "perlio" support from your perl to be able
530 to write stringified archives.
531 Don't change this variable unless you really know what you're doing.
533 $Archive::Tar::ZERO_PAD_NUMBERS
535 This variable holds a boolean indicating if we will create zero padded
536 numbers for "size", "mtime" and "checksum". The default is 0,
537 indicating that we will create space padded numbers. Added for
538 compatibility with "busybox" implementations.
539
541 What's the minimum perl version required to run Archive::Tar?
542 You will need perl version 5.005_03 or newer.
543 Isn't Archive::Tar slow?
545 Yes it is. It's pure perl, so it's a lot slower then your
546 "/bin/tar" However, it's very portable. If speed is an issue,
547 consider using "/bin/tar" instead.
548 Isn't Archive::Tar heavier on memory than /bin/tar?
550 Yes it is, see previous answer. Since "Compress::Zlib" and
551 therefore "IO::Zlib" doesn't support "seek" on their filehandles,
552 there is little choice but to read the archive into memory. This
553 is ok if you want to do in-memory manipulation of the archive.
554 If you just want to extract, use the "extract_archive" class method
556 instead. It will optimize and write to disk immediately.
557 Another option is to use the "iter" class method to iterate over
559 the files in the tarball without reading them all in memory at
560 once.
561 Can you lazy-load data instead?
563 In some cases, yes. You can use the "iter" class method to iterate
564 over the files in the tarball without reading them all in memory at
565 once.
566 How much memory will an X kb tar file need?
568 Probably more than X kb, since it will all be read into memory. If
569 this is a problem, and you don't need to do in memory manipulation
570 of the archive, consider using the "iter" class method, or
571 "/bin/tar" instead.
572 What do you do with unsupported filetypes in an archive?
574 "Unix" has a few filetypes that aren't supported on other
575 platforms, like "Win32". If we encounter a "hardlink" or "symlink"
576 we'll just try to make a copy of the original file, rather than
577 throwing an error.
578 This does require you to read the entire archive in to memory
580 first, since otherwise we wouldn't know what data to fill the copy
581 with. (This means that you cannot use the class methods, including
582 "iter" on archives that have incompatible filetypes and still
583 expect things to work).
584 For other filetypes, like "chardevs" and "blockdevs" we'll warn
586 that the extraction of this particular item didn't work.
587 I'm using WinZip, or some other non-POSIX client, and files are not
589 being extracted properly!
590 By default, "Archive::Tar" is in a completely POSIX-compatible
591 mode, which uses the POSIX-specification of "tar" to store files.
592 For paths greather than 100 characters, this is done using the
593 "POSIX header prefix". Non-POSIX-compatible clients may not support
594 this part of the specification, and may only support the "GNU
595 Extended Header" functionality. To facilitate those clients, you
596 can set the $Archive::Tar::DO_NOT_USE_PREFIX variable to "true".
597 See the "GLOBAL VARIABLES" section for details on this variable.
598 Note that GNU tar earlier than version 1.14 does not cope well with
600 the "POSIX header prefix". If you use such a version, consider
601 setting the $Archive::Tar::DO_NOT_USE_PREFIX variable to "true".
602 How do I extract only files that have property X from an archive?
604 Sometimes, you might not wish to extract a complete archive, just
605 the files that are relevant to you, based on some criteria.
606 You can do this by filtering a list of "Archive::Tar::File" objects
608 based on your criteria. For example, to extract only files that
609 have the string "foo" in their title, you would use:
610 $tar->extract(
612 grep { $_->full_path =~ /foo/ } $tar->get_files
613 );
614 This way, you can filter on any attribute of the files in the
616 archive. Consult the "Archive::Tar::File" documentation on how to
617 use these objects.
618 How do I access .tar.Z files?
620 The "Archive::Tar" module can optionally use "Compress::Zlib" (via
621 the "IO::Zlib" module) to access tar files that have been
622 compressed with "gzip". Unfortunately tar files compressed with the
623 Unix "compress" utility cannot be read by "Compress::Zlib" and so
624 cannot be directly accesses by "Archive::Tar".
625 If the "uncompress" or "gunzip" programs are available, you can use
627 one of these workarounds to read ".tar.Z" files from "Archive::Tar"
628 Firstly with "uncompress"
630 use Archive::Tar;
632 open F, "uncompress -c $filename |";
634 my $tar = Archive::Tar->new(*F);
635 ...
636 and this with "gunzip"
638 use Archive::Tar;
640 open F, "gunzip -c $filename |";
642 my $tar = Archive::Tar->new(*F);
643 ...
644 Similarly, if the "compress" program is available, you can use this
646 to write a ".tar.Z" file
647 use Archive::Tar;
649 use IO::File;
650 my $fh = new IO::File "| compress -c >$filename";
652 my $tar = Archive::Tar->new();
653 ...
654 $tar->write($fh);
655 $fh->close ;
656 How do I handle Unicode strings?
658 "Archive::Tar" uses byte semantics for any files it reads from or
659 writes to disk. This is not a problem if you only deal with files
660 and never look at their content or work solely with byte strings.
661 But if you use Unicode strings with character semantics, some
662 additional steps need to be taken.
663 For example, if you add a Unicode string like
665 # Problem
667 $tar->add_data('file.txt', "Euro: \x{20AC}");
668 then there will be a problem later when the tarfile gets written
670 out to disk via "$tar-"write()>:
671 Wide character in print at .../Archive/Tar.pm line 1014.
673 The data was added as a Unicode string and when writing it out to
675 disk, the ":utf8" line discipline wasn't set by "Archive::Tar", so
676 Perl tried to convert the string to ISO-8859 and failed. The
677 written file now contains garbage.
678 For this reason, Unicode strings need to be converted to
680 UTF-8-encoded bytestrings before they are handed off to
681 "add_data()":
682 use Encode;
684 my $data = "Accented character: \x{20AC}";
685 $data = encode('utf8', $data);
686 $tar->add_data('file.txt', $data);
688 A opposite problem occurs if you extract a UTF8-encoded file from a
690 tarball. Using "get_content()" on the "Archive::Tar::File" object
691 will return its content as a bytestring, not as a Unicode string.
692 If you want it to be a Unicode string (because you want character
694 semantics with operations like regular expression matching), you
695 need to decode the UTF8-encoded content and have Perl convert it
696 into a Unicode string:
697 use Encode;
699 my $data = $tar->get_content();
700 # Make it a Unicode string
702 $data = decode('utf8', $data);
703 There is no easy way to provide this functionality in
705 "Archive::Tar", because a tarball can contain many files, and each
706 of which could be encoded in a different way.
707
709 The AIX tar does not fill all unused space in the tar archive with
710 0x00. This sometimes leads to warning messages from "Archive::Tar".
711 Invalid header block at offset nnn
713 A fix for that problem is scheduled to be released in the following
715 levels of AIX, all of which should be coming out in the 4th quarter of
716 2009:
717 AIX 5.3 TL7 SP10
719 AIX 5.3 TL8 SP8
720 AIX 5.3 TL9 SP5
721 AIX 5.3 TL10 SP2
722 AIX 6.1 TL0 SP11
724 AIX 6.1 TL1 SP7
725 AIX 6.1 TL2 SP6
726 AIX 6.1 TL3 SP3
727 The IBM APAR number for this problem is IZ50240 (Reported component ID:
729 5765G0300 / AIX 5.3). It is possible to get an ifix for that problem.
730 If you need an ifix please contact your local IBM AIX support.
731
733 Check if passed in handles are open for read/write
734 Currently I don't know of any portable pure perl way to do this.
735 Suggestions welcome.
736 Allow archives to be passed in as string
738 Currently, we only allow opened filehandles or filenames, but not
739 strings. The internals would need some reworking to facilitate
740 stringified archives.
741 Facilitate processing an opened filehandle of a compressed archive
743 Currently, we only support this if the filehandle is an IO::Zlib
744 object. Environments, like apache, will present you with an opened
745 filehandle to an uploaded file, which might be a compressed
746 archive.
747
749 The GNU tar specification
750 "http://www.gnu.org/software/tar/manual/tar.html"
751 The PAX format specication
753 The specifcation which tar derives from; "
754 http://www.opengroup.org/onlinepubs/007904975/utilities/pax.html"
755 A comparison of GNU and POSIX tar standards;
757 "http://www.delorie.com/gnu/docs/tar/tar_114.html"
758 GNU tar intends to switch to POSIX compatibility
759 GNU Tar authors have expressed their intention to become completely
760 POSIX-compatible;
761 "http://www.gnu.org/software/tar/manual/html_node/Formats.html"
762 A Comparison between various tar implementations
764 Lists known issues and incompatibilities;
765 "http://gd.tuwien.ac.at/utils/archivers/star/README.otherbugs"
766
768 This module by Jos Boumans <kane@cpan.org>.
769 Please reports bugs to <bug-archive-tar@rt.cpan.org>.
771
773 Thanks to Sean Burke, Chris Nandor, Chip Salzenberg, Tim Heaney, Gisle
774 Aas, Rainer Tammer and especially Andrew Savige for their help and
775 suggestions.
776
778 This module is copyright (c) 2002 - 2009 Jos Boumans <kane@cpan.org>.
779 All rights reserved.
780 This library is free software; you may redistribute and/or modify it
782 under the same terms as Perl itself.
783perl v5.10.1 2017-03-22 Archive::Tar(3pm)