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           $tar->write('files.txz', COMPRESS_XZ);      # xz compressed
27

DESCRIPTION

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

Object Methods

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

Class Methods

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

GLOBAL VARIABLES

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

FAQ

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

CAVEATS

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

TODO

786       Check if passed in handles are open for read/write
787           Currently I don't know of any portable pure perl way to do this.
788           Suggestions welcome.
789
790       Allow archives to be passed in as string
791           Currently, we only allow opened filehandles or filenames, but not
792           strings. The internals would need some reworking to facilitate
793           stringified archives.
794
795       Facilitate processing an opened filehandle of a compressed archive
796           Currently, we only support this if the filehandle is an IO::Zlib
797           object.  Environments, like apache, will present you with an opened
798           filehandle to an uploaded file, which might be a compressed
799           archive.
800

SEE ALSO

802       The GNU tar specification
803           "http://www.gnu.org/software/tar/manual/tar.html"
804
805       The PAX format specification
806           The specification which tar derives from; "
807           http://www.opengroup.org/onlinepubs/007904975/utilities/pax.html"
808
809       A comparison of GNU and POSIX tar standards;
810       "http://www.delorie.com/gnu/docs/tar/tar_114.html"
811       GNU tar intends to switch to POSIX compatibility
812           GNU Tar authors have expressed their intention to become completely
813           POSIX-compatible;
814           "http://www.gnu.org/software/tar/manual/html_node/Formats.html"
815
816       A Comparison between various tar implementations
817           Lists known issues and incompatibilities;
818           "http://gd.tuwien.ac.at/utils/archivers/star/README.otherbugs"
819

AUTHOR

821       This module by Jos Boumans <kane@cpan.org>.
822
823       Please reports bugs to <bug-archive-tar@rt.cpan.org>.
824

ACKNOWLEDGEMENTS

826       Thanks to Sean Burke, Chris Nandor, Chip Salzenberg, Tim Heaney, Gisle
827       Aas, Rainer Tammer and especially Andrew Savige for their help and
828       suggestions.
829
831       This module is copyright (c) 2002 - 2009 Jos Boumans <kane@cpan.org>.
832       All rights reserved.
833
834       This library is free software; you may redistribute and/or modify it
835       under the same terms as Perl itself.
836
837
838
839perl v5.34.0                      2021-08-02                   Archive::Tar(3)
Impressum