1Archive::Tar(3)       User Contributed Perl Documentation      Archive::Tar(3)
2
3
4

NAME

6       Archive::Tar - module for manipulations of tar archives
7

SYNOPSIS

9           use Archive::Tar;
10           my $tar = Archive::Tar->new;
11
12           $tar->read('origin.tgz');
13           $tar->extract();
14
15           $tar->add_files('file/foo.pl', 'docs/README');
16           $tar->add_data('file/baz.txt', 'This is the contents now');
17
18           $tar->rename('oldname', 'new/file/name');
19           $tar->chown('/', 'root');
20           $tar->chown('/', 'root:root');
21           $tar->chmod('/tmp', '1777');
22
23           $tar->write('files.tar');                   # plain tar
24           $tar->write('files.tgz', COMPRESS_GZIP);    # gzip compressed
25           $tar->write('files.tbz', COMPRESS_BZIP);    # bzip2 compressed
26

DESCRIPTION

28       Archive::Tar provides an object oriented mechanism for handling tar
29       files.  It provides class methods for quick and easy files handling
30       while also allowing for the creation of tar file objects for custom
31       manipulation.  If you have the IO::Zlib module installed, Archive::Tar
32       will also support compressed or gzipped tar files.
33
34       An object of class Archive::Tar represents a .tar(.gz) archive full of
35       files and things.
36

Object Methods

38   Archive::Tar->new( [$file, $compressed] )
39       Returns a new Tar object. If given any arguments, "new()" calls the
40       "read()" method automatically, passing on the arguments provided to the
41       "read()" method.
42
43       If "new()" is invoked with arguments and the "read()" method fails for
44       any reason, "new()" returns undef.
45
46   $tar->read ( $filename|$handle, [$compressed, {opt => 'val'}] )
47       Read the given tar file into memory.  The first argument can either be
48       the name of a file or a reference to an already open filehandle (or an
49       IO::Zlib object if it's compressed)
50
51       The "read" will replace any previous content in $tar!
52
53       The second argument may be considered optional, but remains for
54       backwards compatibility. Archive::Tar now looks at the file magic to
55       determine what class should be used to open the file and will
56       transparently Do The Right Thing.
57
58       Archive::Tar will warn if you try to pass a bzip2 compressed file and
59       the IO::Zlib / IO::Uncompress::Bunzip2 modules are not available and
60       simply return.
61
62       Note that you can currently not pass a "gzip" compressed filehandle,
63       which is not opened with "IO::Zlib", a "bzip2" compressed filehandle,
64       which is not opened with "IO::Uncompress::Bunzip2", nor a string
65       containing the full archive information (either compressed or
66       uncompressed). These are worth while features, but not currently
67       implemented. See the "TODO" section.
68
69       The third argument can be a hash reference with options. Note that all
70       options are case-sensitive.
71
72       limit
73           Do not read more than "limit" files. This is useful if you have
74           very big archives, and are only interested in the first few files.
75
76       filter
77           Can be set to a regular expression.  Only files with names that
78           match the expression will be read.
79
80       md5 Set to 1 and the md5sum of files will be returned (instead of file
81           data)
82               my $iter = Archive::Tar->iter( $file,  1, {md5 => 1} );
83               while( my $f = $iter->() ) {
84                   print $f->data . "\t" . $f->full_path . $/;
85               }
86
87       extract
88           If set to true, immediately extract entries when reading them. This
89           gives you the same memory break as the "extract_archive" function.
90           Note however that entries will not be read into memory, but written
91           straight to disk. This means no "Archive::Tar::File" objects are
92           created for you to inspect.
93
94       All files are stored internally as "Archive::Tar::File" objects.
95       Please consult the Archive::Tar::File documentation for details.
96
97       Returns the number of files read in scalar context, and a list of
98       "Archive::Tar::File" objects in list context.
99
100   $tar->contains_file( $filename )
101       Check if the archive contains a certain file.  It will return true if
102       the file is in the archive, false otherwise.
103
104       Note however, that this function does an exact match using "eq" on the
105       full path. So it cannot compensate for case-insensitive file- systems
106       or compare 2 paths to see if they would point to the same underlying
107       file.
108
109   $tar->extract( [@filenames] )
110       Write files whose names are equivalent to any of the names in
111       @filenames to disk, creating subdirectories as necessary. This might
112       not work too well under VMS.  Under MacPerl, the file's modification
113       time will be converted to the MacOS zero of time, and appropriate
114       conversions will be done to the path.  However, the length of each
115       element of the path is not inspected to see whether it's longer than
116       MacOS currently allows (32 characters).
117
118       If "extract" is called without a list of file names, the entire
119       contents of the archive are extracted.
120
121       Returns a list of filenames extracted.
122
123   $tar->extract_file( $file, [$extract_path] )
124       Write an entry, whose name is equivalent to the file name provided to
125       disk. Optionally takes a second parameter, which is the full native
126       path (including filename) the entry will be written to.
127
128       For example:
129
130           $tar->extract_file( 'name/in/archive', 'name/i/want/to/give/it' );
131
132           $tar->extract_file( $at_file_object,   'name/i/want/to/give/it' );
133
134       Returns true on success, false on failure.
135
136   $tar->list_files( [\@properties] )
137       Returns a list of the names of all the files in the archive.
138
139       If "list_files()" is passed an array reference as its first argument it
140       returns a list of hash references containing the requested properties
141       of each file.  The following list of properties is supported: name,
142       size, mtime (last modified date), mode, uid, gid, linkname, uname,
143       gname, devmajor, devminor, prefix.
144
145       Passing an array reference containing only one element, 'name', is
146       special cased to return a list of names rather than a list of hash
147       references, making it equivalent to calling "list_files" without
148       arguments.
149
150   $tar->get_files( [@filenames] )
151       Returns the "Archive::Tar::File" objects matching the filenames
152       provided. If no filename list was passed, all "Archive::Tar::File"
153       objects in the current Tar object are returned.
154
155       Please refer to the "Archive::Tar::File" documentation on how to handle
156       these objects.
157
158   $tar->get_content( $file )
159       Return the content of the named file.
160
161   $tar->replace_content( $file, $content )
162       Make the string $content be the content for the file named $file.
163
164   $tar->rename( $file, $new_name )
165       Rename the file of the in-memory archive to $new_name.
166
167       Note that you must specify a Unix path for $new_name, since per tar
168       standard, all files in the archive must be Unix paths.
169
170       Returns true on success and false on failure.
171
172   $tar->chmod( $file, $mode )
173       Change mode of $file to $mode.
174
175       Returns true on success and false on failure.
176
177   $tar->chown( $file, $uname [, $gname] )
178       Change owner $file to $uname and $gname.
179
180       Returns true on success and false on failure.
181
182   $tar->remove (@filenamelist)
183       Removes any entries with names matching any of the given filenames from
184       the in-memory archive. Returns a list of "Archive::Tar::File" objects
185       that remain.
186
187   $tar->clear
188       "clear" clears the current in-memory archive. This effectively gives
189       you a 'blank' object, ready to be filled again. Note that "clear" only
190       has effect on the object, not the underlying tarfile.
191
192   $tar->write ( [$file, $compressed, $prefix] )
193       Write the in-memory archive to disk.  The first argument can either be
194       the name of a file or a reference to an already open filehandle (a GLOB
195       reference).
196
197       The second argument is used to indicate compression. You can either
198       compress using "gzip" or "bzip2". If you pass a digit, it's assumed to
199       be the "gzip" compression level (between 1 and 9), but the use of
200       constants is preferred:
201
202         # write a gzip compressed file
203         $tar->write( 'out.tgz', COMPRESS_GZIP );
204
205         # write a bzip compressed file
206         $tar->write( 'out.tbz', COMPRESS_BZIP );
207
208       Note that when you pass in a filehandle, the compression argument is
209       ignored, as all files are printed verbatim to your filehandle.  If you
210       wish to enable compression with filehandles, use an "IO::Zlib" or
211       "IO::Compress::Bzip2" filehandle instead.
212
213       The third argument is an optional prefix. All files will be tucked away
214       in the directory you specify as prefix. So if you have files 'a' and
215       'b' in your archive, and you specify 'foo' as prefix, they will be
216       written to the archive as 'foo/a' and 'foo/b'.
217
218       If no arguments are given, "write" returns the entire formatted archive
219       as a string, which could be useful if you'd like to stuff the archive
220       into a socket or a pipe to gzip or something.
221
222   $tar->add_files( @filenamelist )
223       Takes a list of filenames and adds them to the in-memory archive.
224
225       The path to the file is automatically converted to a Unix like
226       equivalent for use in the archive, and, if on MacOS, the file's
227       modification time is converted from the MacOS epoch to the Unix epoch.
228       So tar archives created on MacOS with Archive::Tar can be read both
229       with tar on Unix and applications like suntar or Stuffit Expander on
230       MacOS.
231
232       Be aware that the file's type/creator and resource fork will be lost,
233       which is usually what you want in cross-platform archives.
234
235       Instead of a filename, you can also pass it an existing
236       "Archive::Tar::File" object from, for example, another archive. The
237       object will be clone, and effectively be a copy of the original, not an
238       alias.
239
240       Returns a list of "Archive::Tar::File" objects that were just added.
241
242   $tar->add_data ( $filename, $data, [$opthashref] )
243       Takes a filename, a scalar full of data and optionally a reference to a
244       hash with specific options.
245
246       Will add a file to the in-memory archive, with name $filename and
247       content $data. Specific properties can be set using $opthashref.  The
248       following list of properties is supported: name, size, mtime (last
249       modified date), mode, uid, gid, linkname, uname, gname, devmajor,
250       devminor, prefix, type.  (On MacOS, the file's path and modification
251       times are converted to Unix equivalents.)
252
253       Valid values for the file type are the following constants defined by
254       Archive::Tar::Constant:
255
256       FILE
257           Regular file.
258
259       HARDLINK
260       SYMLINK
261           Hard and symbolic ("soft") links; linkname should specify target.
262
263       CHARDEV
264       BLOCKDEV
265           Character and block devices. devmajor and devminor should specify
266           the major and minor device numbers.
267
268       DIR Directory.
269
270       FIFO
271           FIFO (named pipe).
272
273       SOCKET
274           Socket.
275
276       Returns the "Archive::Tar::File" object that was just added, or "undef"
277       on failure.
278
279   $tar->error( [$BOOL] )
280       Returns the current error string (usually, the last error reported).
281       If a true value was specified, it will give the "Carp::longmess"
282       equivalent of the error, in effect giving you a stacktrace.
283
284       For backwards compatibility, this error is also available as
285       $Archive::Tar::error although it is much recommended you use the method
286       call instead.
287
288   $tar->setcwd( $cwd );
289       "Archive::Tar" needs to know the current directory, and it will run
290       "Cwd::cwd()" every time it extracts a relative entry from the tarfile
291       and saves it in the file system. (As of version 1.30, however,
292       "Archive::Tar" will use the speed optimization described below
293       automatically, so it's only relevant if you're using "extract_file()").
294
295       Since "Archive::Tar" doesn't change the current directory internally
296       while it is extracting the items in a tarball, all calls to
297       "Cwd::cwd()" can be avoided if we can guarantee that the current
298       directory doesn't get changed externally.
299
300       To use this performance boost, set the current directory via
301
302           use Cwd;
303           $tar->setcwd( cwd() );
304
305       once before calling a function like "extract_file" and "Archive::Tar"
306       will use the current directory setting from then on and won't call
307       "Cwd::cwd()" internally.
308
309       To switch back to the default behaviour, use
310
311           $tar->setcwd( undef );
312
313       and "Archive::Tar" will call "Cwd::cwd()" internally again.
314
315       If you're using "Archive::Tar"'s "extract()" method, "setcwd()" will be
316       called for you.
317

Class Methods

319   Archive::Tar->create_archive($file, $compressed, @filelist)
320       Creates a tar file from the list of files provided.  The first argument
321       can either be the name of the tar file to create or a reference to an
322       open file handle (e.g. a GLOB reference).
323
324       The second argument is used to indicate compression. You can either
325       compress using "gzip" or "bzip2". If you pass a digit, it's assumed to
326       be the "gzip" compression level (between 1 and 9), but the use of
327       constants is preferred:
328
329         # write a gzip compressed file
330         Archive::Tar->create_archive( 'out.tgz', COMPRESS_GZIP, @filelist );
331
332         # write a bzip compressed file
333         Archive::Tar->create_archive( 'out.tbz', COMPRESS_BZIP, @filelist );
334
335       Note that when you pass in a filehandle, the compression argument is
336       ignored, as all files are printed verbatim to your filehandle.  If you
337       wish to enable compression with filehandles, use an "IO::Zlib" or
338       "IO::Compress::Bzip2" filehandle instead.
339
340       The remaining arguments list the files to be included in the tar file.
341       These files must all exist. Any files which don't exist or can't be
342       read are silently ignored.
343
344       If the archive creation fails for any reason, "create_archive" will
345       return false. Please use the "error" method to find the cause of the
346       failure.
347
348       Note that this method does not write "on the fly" as it were; it still
349       reads all the files into memory before writing out the archive.
350       Consult the FAQ below if this is a problem.
351
352   Archive::Tar->iter( $filename, [ $compressed, {opt => $val} ] )
353       Returns an iterator function that reads the tar file without loading it
354       all in memory.  Each time the function is called it will return the
355       next file in the tarball. The files are returned as
356       "Archive::Tar::File" objects. The iterator function returns the empty
357       list once it has exhausted the files contained.
358
359       The second argument can be a hash reference with options, which are
360       identical to the arguments passed to "read()".
361
362       Example usage:
363
364           my $next = Archive::Tar->iter( "example.tar.gz", 1, {filter => qr/\.pm$/} );
365
366           while( my $f = $next->() ) {
367               print $f->name, "\n";
368
369               $f->extract or warn "Extraction failed";
370
371               # ....
372           }
373
374   Archive::Tar->list_archive($file, $compressed, [\@properties])
375       Returns a list of the names of all the files in the archive.  The first
376       argument can either be the name of the tar file to list or a reference
377       to an open file handle (e.g. a GLOB reference).
378
379       If "list_archive()" is passed an array reference as its third argument
380       it returns a list of hash references containing the requested
381       properties of each file.  The following list of properties is
382       supported: full_path, name, size, mtime (last modified date), mode,
383       uid, gid, linkname, uname, gname, devmajor, devminor, prefix, type.
384
385       See "Archive::Tar::File" for details about supported properties.
386
387       Passing an array reference containing only one element, 'name', is
388       special cased to return a list of names rather than a list of hash
389       references.
390
391   Archive::Tar->extract_archive($file, $compressed)
392       Extracts the contents of the tar file.  The first argument can either
393       be the name of the tar file to create or a reference to an open file
394       handle (e.g. a GLOB reference).  All relative paths in the tar file
395       will be created underneath the current working directory.
396
397       "extract_archive" will return a list of files it extracted.  If the
398       archive extraction fails for any reason, "extract_archive" will return
399       false.  Please use the "error" method to find the cause of the failure.
400
401   $bool = Archive::Tar->has_io_string
402       Returns true if we currently have "IO::String" support loaded.
403
404       Either "IO::String" or "perlio" support is needed to support writing
405       stringified archives. Currently, "perlio" is the preferred method, if
406       available.
407
408       See the "GLOBAL VARIABLES" section to see how to change this
409       preference.
410
411   $bool = Archive::Tar->has_perlio
412       Returns true if we currently have "perlio" support loaded.
413
414       This requires "perl-5.8" or higher, compiled with "perlio"
415
416       Either "IO::String" or "perlio" support is needed to support writing
417       stringified archives. Currently, "perlio" is the preferred method, if
418       available.
419
420       See the "GLOBAL VARIABLES" section to see how to change this
421       preference.
422
423   $bool = Archive::Tar->has_zlib_support
424       Returns true if "Archive::Tar" can extract "zlib" compressed archives
425
426   $bool = Archive::Tar->has_bzip2_support
427       Returns true if "Archive::Tar" can extract "bzip2" compressed archives
428
429   Archive::Tar->can_handle_compressed_files
430       A simple checking routine, which will return true if "Archive::Tar" is
431       able to uncompress compressed archives on the fly with "IO::Zlib" and
432       "IO::Compress::Bzip2" or false if not both are installed.
433
434       You can use this as a shortcut to determine whether "Archive::Tar" will
435       do what you think before passing compressed archives to its "read"
436       method.
437

GLOBAL VARIABLES

439   $Archive::Tar::FOLLOW_SYMLINK
440       Set this variable to 1 to make "Archive::Tar" effectively make a copy
441       of the file when extracting. Default is 0, which means the symlink
442       stays intact. Of course, you will have to pack the file linked to as
443       well.
444
445       This option is checked when you write out the tarfile using "write" or
446       "create_archive".
447
448       This works just like "/bin/tar"'s "-h" option.
449
450   $Archive::Tar::CHOWN
451       By default, "Archive::Tar" will try to "chown" your files if it is able
452       to. In some cases, this may not be desired. In that case, set this
453       variable to 0 to disable "chown"-ing, even if it were possible.
454
455       The default is 1.
456
457   $Archive::Tar::CHMOD
458       By default, "Archive::Tar" will try to "chmod" your files to whatever
459       mode was specified for the particular file in the archive.  In some
460       cases, this may not be desired. In that case, set this variable to 0 to
461       disable "chmod"-ing.
462
463       The default is 1.
464
465   $Archive::Tar::SAME_PERMISSIONS
466       When, $Archive::Tar::CHMOD is enabled, this setting controls whether
467       the permissions on files from the archive are used without modification
468       of if they are filtered by removing any setid bits and applying the
469       current umask.
470
471       The default is 1 for the root user and 0 for normal users.
472
473   $Archive::Tar::DO_NOT_USE_PREFIX
474       By default, "Archive::Tar" will try to put paths that are over 100
475       characters in the "prefix" field of your tar header, as defined per
476       POSIX-standard. However, some (older) tar programs do not implement
477       this spec. To retain compatibility with these older or non-POSIX
478       compliant versions, you can set the $DO_NOT_USE_PREFIX variable to a
479       true value, and "Archive::Tar" will use an alternate way of dealing
480       with paths over 100 characters by using the "GNU Extended Header"
481       feature.
482
483       Note that clients who do not support the "GNU Extended Header" feature
484       will not be able to read these archives. Such clients include tars on
485       "Solaris", "Irix" and "AIX".
486
487       The default is 0.
488
489   $Archive::Tar::DEBUG
490       Set this variable to 1 to always get the "Carp::longmess" output of the
491       warnings, instead of the regular "carp". This is the same message you
492       would get by doing:
493
494           $tar->error(1);
495
496       Defaults to 0.
497
498   $Archive::Tar::WARN
499       Set this variable to 0 if you do not want any warnings printed.
500       Personally I recommend against doing this, but people asked for the
501       option. Also, be advised that this is of course not threadsafe.
502
503       Defaults to 1.
504
505   $Archive::Tar::error
506       Holds the last reported error. Kept for historical reasons, but its use
507       is very much discouraged. Use the "error()" method instead:
508
509           warn $tar->error unless $tar->extract;
510
511       Note that in older versions of this module, the "error()" method would
512       return an effectively global value even when called an instance method
513       as above. This has since been fixed, and multiple instances of
514       "Archive::Tar" now have separate error strings.
515
516   $Archive::Tar::INSECURE_EXTRACT_MODE
517       This variable indicates whether "Archive::Tar" should allow files to be
518       extracted outside their current working directory.
519
520       Allowing this could have security implications, as a malicious tar
521       archive could alter or replace any file the extracting user has
522       permissions to. Therefor, the default is to not allow insecure
523       extractions.
524
525       If you trust the archive, or have other reasons to allow the archive to
526       write files outside your current working directory, set this variable
527       to "true".
528
529       Note that this is a backwards incompatible change from version 1.36 and
530       before.
531
532   $Archive::Tar::HAS_PERLIO
533       This variable holds a boolean indicating if we currently have "perlio"
534       support loaded. This will be enabled for any perl greater than 5.8
535       compiled with "perlio".
536
537       If you feel strongly about disabling it, set this variable to "false".
538       Note that you will then need "IO::String" installed to support writing
539       stringified archives.
540
541       Don't change this variable unless you really know what you're doing.
542
543   $Archive::Tar::HAS_IO_STRING
544       This variable holds a boolean indicating if we currently have
545       "IO::String" support loaded. This will be enabled for any perl that has
546       a loadable "IO::String" module.
547
548       If you feel strongly about disabling it, set this variable to "false".
549       Note that you will then need "perlio" support from your perl to be able
550       to  write stringified archives.
551
552       Don't change this variable unless you really know what you're doing.
553
554   $Archive::Tar::ZERO_PAD_NUMBERS
555       This variable holds a boolean indicating if we will create zero padded
556       numbers for "size", "mtime" and "checksum".  The default is 0,
557       indicating that we will create space padded numbers. Added for
558       compatibility with "busybox" implementations.
559
560   Tuning the way RESOLVE_SYMLINK will works
561               You can tune the behaviour by setting the $Archive::Tar::RESOLVE_SYMLINK variable,
562               or $ENV{PERL5_AT_RESOLVE_SYMLINK} before loading the module Archive::Tar.
563
564         Values can be one of the following:
565
566                       none
567                  Disable this mechanism and failed as it was in previous version (<1.88)
568
569                       speed (default)
570                  If you prefer speed
571                  this will read again the whole archive using read() so all entries
572                  will be available
573
574           memory
575                  If you prefer memory
576
577               Limitation
578
579                       It won't work for terminal, pipe or sockets or every non seekable source.
580

FAQ

582       What's the minimum perl version required to run Archive::Tar?
583           You will need perl version 5.005_03 or newer.
584
585       Isn't Archive::Tar slow?
586           Yes it is. It's pure perl, so it's a lot slower then your
587           "/bin/tar" However, it's very portable. If speed is an issue,
588           consider using "/bin/tar" instead.
589
590       Isn't Archive::Tar heavier on memory than /bin/tar?
591           Yes it is, see previous answer. Since "Compress::Zlib" and
592           therefore "IO::Zlib" doesn't support "seek" on their filehandles,
593           there is little choice but to read the archive into memory.  This
594           is ok if you want to do in-memory manipulation of the archive.
595
596           If you just want to extract, use the "extract_archive" class method
597           instead. It will optimize and write to disk immediately.
598
599           Another option is to use the "iter" class method to iterate over
600           the files in the tarball without reading them all in memory at
601           once.
602
603       Can you lazy-load data instead?
604           In some cases, yes. You can use the "iter" class method to iterate
605           over the files in the tarball without reading them all in memory at
606           once.
607
608       How much memory will an X kb tar file need?
609           Probably more than X kb, since it will all be read into memory. If
610           this is a problem, and you don't need to do in memory manipulation
611           of the archive, consider using the "iter" class method, or
612           "/bin/tar" instead.
613
614       What do you do with unsupported filetypes in an archive?
615           "Unix" has a few filetypes that aren't supported on other
616           platforms, like "Win32". If we encounter a "hardlink" or "symlink"
617           we'll just try to make a copy of the original file, rather than
618           throwing an error.
619
620           This does require you to read the entire archive in to memory
621           first, since otherwise we wouldn't know what data to fill the copy
622           with.  (This means that you cannot use the class methods, including
623           "iter" on archives that have incompatible filetypes and still
624           expect things to work).
625
626           For other filetypes, like "chardevs" and "blockdevs" we'll warn
627           that the extraction of this particular item didn't work.
628
629       I'm using WinZip, or some other non-POSIX client, and files are not
630       being extracted properly!
631           By default, "Archive::Tar" is in a completely POSIX-compatible
632           mode, which uses the POSIX-specification of "tar" to store files.
633           For paths greater than 100 characters, this is done using the
634           "POSIX header prefix". Non-POSIX-compatible clients may not support
635           this part of the specification, and may only support the "GNU
636           Extended Header" functionality. To facilitate those clients, you
637           can set the $Archive::Tar::DO_NOT_USE_PREFIX variable to "true".
638           See the "GLOBAL VARIABLES" section for details on this variable.
639
640           Note that GNU tar earlier than version 1.14 does not cope well with
641           the "POSIX header prefix". If you use such a version, consider
642           setting the $Archive::Tar::DO_NOT_USE_PREFIX variable to "true".
643
644       How do I extract only files that have property X from an archive?
645           Sometimes, you might not wish to extract a complete archive, just
646           the files that are relevant to you, based on some criteria.
647
648           You can do this by filtering a list of "Archive::Tar::File" objects
649           based on your criteria. For example, to extract only files that
650           have the string "foo" in their title, you would use:
651
652               $tar->extract(
653                   grep { $_->full_path =~ /foo/ } $tar->get_files
654               );
655
656           This way, you can filter on any attribute of the files in the
657           archive.  Consult the "Archive::Tar::File" documentation on how to
658           use these objects.
659
660       How do I access .tar.Z files?
661           The "Archive::Tar" module can optionally use "Compress::Zlib" (via
662           the "IO::Zlib" module) to access tar files that have been
663           compressed with "gzip". Unfortunately tar files compressed with the
664           Unix "compress" utility cannot be read by "Compress::Zlib" and so
665           cannot be directly accesses by "Archive::Tar".
666
667           If the "uncompress" or "gunzip" programs are available, you can use
668           one of these workarounds to read ".tar.Z" files from "Archive::Tar"
669
670           Firstly with "uncompress"
671
672               use Archive::Tar;
673
674               open F, "uncompress -c $filename |";
675               my $tar = Archive::Tar->new(*F);
676               ...
677
678           and this with "gunzip"
679
680               use Archive::Tar;
681
682               open F, "gunzip -c $filename |";
683               my $tar = Archive::Tar->new(*F);
684               ...
685
686           Similarly, if the "compress" program is available, you can use this
687           to write a ".tar.Z" file
688
689               use Archive::Tar;
690               use IO::File;
691
692               my $fh = new IO::File "| compress -c >$filename";
693               my $tar = Archive::Tar->new();
694               ...
695               $tar->write($fh);
696               $fh->close ;
697
698       How do I handle Unicode strings?
699           "Archive::Tar" uses byte semantics for any files it reads from or
700           writes to disk. This is not a problem if you only deal with files
701           and never look at their content or work solely with byte strings.
702           But if you use Unicode strings with character semantics, some
703           additional steps need to be taken.
704
705           For example, if you add a Unicode string like
706
707               # Problem
708               $tar->add_data('file.txt', "Euro: \x{20AC}");
709
710           then there will be a problem later when the tarfile gets written
711           out to disk via "$tar->write()":
712
713               Wide character in print at .../Archive/Tar.pm line 1014.
714
715           The data was added as a Unicode string and when writing it out to
716           disk, the ":utf8" line discipline wasn't set by "Archive::Tar", so
717           Perl tried to convert the string to ISO-8859 and failed. The
718           written file now contains garbage.
719
720           For this reason, Unicode strings need to be converted to
721           UTF-8-encoded bytestrings before they are handed off to
722           "add_data()":
723
724               use Encode;
725               my $data = "Accented character: \x{20AC}";
726               $data = encode('utf8', $data);
727
728               $tar->add_data('file.txt', $data);
729
730           A opposite problem occurs if you extract a UTF8-encoded file from a
731           tarball. Using "get_content()" on the "Archive::Tar::File" object
732           will return its content as a bytestring, not as a Unicode string.
733
734           If you want it to be a Unicode string (because you want character
735           semantics with operations like regular expression matching), you
736           need to decode the UTF8-encoded content and have Perl convert it
737           into a Unicode string:
738
739               use Encode;
740               my $data = $tar->get_content();
741
742               # Make it a Unicode string
743               $data = decode('utf8', $data);
744
745           There is no easy way to provide this functionality in
746           "Archive::Tar", because a tarball can contain many files, and each
747           of which could be encoded in a different way.
748

CAVEATS

750       The AIX tar does not fill all unused space in the tar archive with
751       0x00.  This sometimes leads to warning messages from "Archive::Tar".
752
753         Invalid header block at offset nnn
754
755       A fix for that problem is scheduled to be released in the following
756       levels of AIX, all of which should be coming out in the 4th quarter of
757       2009:
758
759        AIX 5.3 TL7 SP10
760        AIX 5.3 TL8 SP8
761        AIX 5.3 TL9 SP5
762        AIX 5.3 TL10 SP2
763
764        AIX 6.1 TL0 SP11
765        AIX 6.1 TL1 SP7
766        AIX 6.1 TL2 SP6
767        AIX 6.1 TL3 SP3
768
769       The IBM APAR number for this problem is IZ50240 (Reported component ID:
770       5765G0300 / AIX 5.3). It is possible to get an ifix for that problem.
771       If you need an ifix please contact your local IBM AIX support.
772

TODO

774       Check if passed in handles are open for read/write
775           Currently I don't know of any portable pure perl way to do this.
776           Suggestions welcome.
777
778       Allow archives to be passed in as string
779           Currently, we only allow opened filehandles or filenames, but not
780           strings. The internals would need some reworking to facilitate
781           stringified archives.
782
783       Facilitate processing an opened filehandle of a compressed archive
784           Currently, we only support this if the filehandle is an IO::Zlib
785           object.  Environments, like apache, will present you with an opened
786           filehandle to an uploaded file, which might be a compressed
787           archive.
788

SEE ALSO

790       The GNU tar specification
791           "http://www.gnu.org/software/tar/manual/tar.html"
792
793       The PAX format specification
794           The specification which tar derives from; "
795           http://www.opengroup.org/onlinepubs/007904975/utilities/pax.html"
796
797       A comparison of GNU and POSIX tar standards;
798       "http://www.delorie.com/gnu/docs/tar/tar_114.html"
799       GNU tar intends to switch to POSIX compatibility
800           GNU Tar authors have expressed their intention to become completely
801           POSIX-compatible;
802           "http://www.gnu.org/software/tar/manual/html_node/Formats.html"
803
804       A Comparison between various tar implementations
805           Lists known issues and incompatibilities;
806           "http://gd.tuwien.ac.at/utils/archivers/star/README.otherbugs"
807

AUTHOR

809       This module by Jos Boumans <kane@cpan.org>.
810
811       Please reports bugs to <bug-archive-tar@rt.cpan.org>.
812

ACKNOWLEDGEMENTS

814       Thanks to Sean Burke, Chris Nandor, Chip Salzenberg, Tim Heaney, Gisle
815       Aas, Rainer Tammer and especially Andrew Savige for their help and
816       suggestions.
817
819       This module is copyright (c) 2002 - 2009 Jos Boumans <kane@cpan.org>.
820       All rights reserved.
821
822       This library is free software; you may redistribute and/or modify it
823       under the same terms as Perl itself.
824
825
826
827perl v5.26.3                      2018-06-19                   Archive::Tar(3)
Impressum