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 any
45       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 and
296       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 Cwd::cwd()
302       can be avoided if we can guarantee that the current directory doesn't
303       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 it
388       returns a list of hash references containing the requested properties
389       of each file.  The following list of properties is supported:
390       full_path, name, size, mtime (last modified date), mode, uid, gid,
391       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
574       $Archive::Tar::RESOLVE_SYMLINK variable, or
575       $ENV{PERL5_AT_RESOLVE_SYMLINK} before loading the module Archive::Tar.
576
577       Values can be one of the following:
578
579       none
580           Disable this mechanism and failed as it was in previous version
581           (<1.88)
582
583       speed (default)
584           If you prefer speed this will read again the whole archive using
585           read() so all entries will be available
586
587       memory
588           If you prefer memory
589
590       Limitation: It won't work for terminal, pipe or sockets or every non
591       seekable source.
592
593   $Archive::Tar::EXTRACT_BLOCK_SIZE
594       This variable holds an integer with the block size that should be used
595       when writing files during extraction. It defaults to 1 GiB. Please note
596       that this cannot be arbitrarily large since some operating systems
597       limit the number of bytes that can be written in one call to write(2),
598       so if this is too large, extraction may fail with an error.
599

FAQ

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

CAVEATS

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

TODO

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

SEE ALSO

808       The GNU tar specification
809           <https://www.gnu.org/software/tar/manual/tar.html>
810
811       The PAX format specification
812           The specification which tar derives from;
813           <https://pubs.opengroup.org/onlinepubs/007904975/utilities/pax.html>
814

AUTHOR

816       This module by Jos Boumans <kane@cpan.org>.
817
818       Please reports bugs to <bug-archive-tar@rt.cpan.org>.
819

ACKNOWLEDGEMENTS

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