Archive::Tar(3pm)

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',1);
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
20           $tar->write('files.tar');
21

DESCRIPTION

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

Object Methods

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

Class Methods

316       Archive::Tar->create_archive($file, $compression, @filelist)
317
318       Creates a tar file from the list of files provided.  The first argument
319       can either be the name of the tar file to create or a reference to an
320       open file handle (e.g. a GLOB reference).
321
322       The second argument specifies the level of compression to be used, if
323       any.  Compression of tar files requires the installation of the
324       IO::Zlib module.  Specific levels of compression may be requested by
325       passing a value between 2 and 9 as the second argument.  Any other
326       value evaluating as true will result in the default compression level
327       being used.
328
329       Note that when you pass in a filehandle, the compression argument is
330       ignored, as all files are printed verbatim to your filehandle.  If you
331       wish to enable compression with filehandles, use an "IO::Zlib" filehan‐
332       dle instead.
333
334       The remaining arguments list the files to be included in the tar file.
335       These files must all exist. Any files which don't exist or can't be
336       read are silently ignored.
337
338       If the archive creation fails for any reason, "create_archive" will
339       return false. Please use the "error" method to find the cause of the
340       failure.
341
342       Note that this method does not write "on the fly" as it were; it still
343       reads all the files into memory before writing out the archive.  Con‐
344       sult the FAQ below if this is a problem.
345
346       Archive::Tar->list_archive ($file, $compressed, [\@properties])
347
348       Returns a list of the names of all the files in the archive.  The first
349       argument can either be the name of the tar file to list or a reference
350       to an open file handle (e.g. a GLOB reference).
351
352       If "list_archive()" is passed an array reference as its third argument
353       it returns a list of hash references containing the requested proper‐
354       ties of each file.  The following list of properties is supported:
355       full_path, name, size, mtime (last modified date), mode, uid, gid,
356       linkname, uname, gname, devmajor, devminor, prefix.
357
358       See "Archive::Tar::File" for details about supported properties.
359
360       Passing an array reference containing only one element, 'name', is spe‐
361       cial cased to return a list of names rather than a list of hash refer‐
362       ences.
363
364       Archive::Tar->extract_archive ($file, $gzip)
365
366       Extracts the contents of the tar file.  The first argument can either
367       be the name of the tar file to create or a reference to an open file
368       handle (e.g. a GLOB reference).  All relative paths in the tar file
369       will be created underneath the current working directory.
370
371       "extract_archive" will return a list of files it extracted.  If the ar‐
372       chive extraction fails for any reason, "extract_archive" will return
373       false.  Please use the "error" method to find the cause of the failure.
374
375       Archive::Tar->can_handle_compressed_files
376
377       A simple checking routine, which will return true if "Archive::Tar" is
378       able to uncompress compressed archives on the fly with "IO::Zlib", or
379       false if "IO::Zlib" is not installed.
380
381       You can use this as a shortcut to determine whether "Archive::Tar" will
382       do what you think before passing compressed archives to its "read"
383       method.
384

GLOBAL VARIABLES

386       $Archive::Tar::FOLLOW_SYMLINK
387
388       Set this variable to 1 to make "Archive::Tar" effectively make a copy
389       of the file when extracting. Default is 0, which means the symlink
390       stays intact. Of course, you will have to pack the file linked to as
391       well.
392
393       This option is checked when you write out the tarfile using "write" or
394       "create_archive".
395
396       This works just like "/bin/tar"'s "-h" option.
397
398       $Archive::Tar::CHOWN
399
400       By default, "Archive::Tar" will try to "chown" your files if it is able
401       to. In some cases, this may not be desired. In that case, set this
402       variable to 0 to disable "chown"-ing, even if it were possible.
403
404       The default is 1.
405
406       $Archive::Tar::CHMOD
407
408       By default, "Archive::Tar" will try to "chmod" your files to whatever
409       mode was specified for the particular file in the archive.  In some
410       cases, this may not be desired. In that case, set this variable to 0 to
411       disable "chmod"-ing.
412
413       The default is 1.
414
415       $Archive::Tar::DO_NOT_USE_PREFIX
416
417       By default, "Archive::Tar" will try to put paths that are over 100
418       characters in the "prefix" field of your tar header, as defined per
419       POSIX-standard. However, some (older) tar programs do not implement
420       this spec. To retain compatibility with these older or non-POSIX com‐
421       pliant versions, you can set the $DO_NOT_USE_PREFIX variable to a true
422       value, and "Archive::Tar" will use an alternate way of dealing with
423       paths over 100 characters by using the "GNU Extended Header" feature.
424
425       Note that clients who do not support the "GNU Extended Header" feature
426       will not be able to read these archives. Such clients include tars on
427       "Solaris", "Irix" and "AIX".
428
429       The default is 0.
430
431       $Archive::Tar::DEBUG
432
433       Set this variable to 1 to always get the "Carp::longmess" output of the
434       warnings, instead of the regular "carp". This is the same message you
435       would get by doing:
436
437           $tar->error(1);
438
439       Defaults to 0.
440
441       $Archive::Tar::WARN
442
443       Set this variable to 0 if you do not want any warnings printed.  Per‐
444       sonally I recommend against doing this, but people asked for the
445       option. Also, be advised that this is of course not threadsafe.
446
447       Defaults to 1.
448
449       $Archive::Tar::error
450
451       Holds the last reported error. Kept for historical reasons, but its use
452       is very much discouraged. Use the "error()" method instead:
453
454           warn $tar->error unless $tar->extract;
455
456       $Archive::Tar::HAS_PERLIO
457
458       This variable holds a boolean indicating if we currently have "perlio"
459       support loaded. This will be enabled for any perl greater than 5.8 com‐
460       piled with "perlio".
461
462       If you feel strongly about disabling it, set this variable to "false".
463       Note that you will then need "IO::String" installed to support writing
464       stringified archives.
465
466       Don't change this variable unless you really know what you're doing.
467
468       $Archive::Tar::HAS_IO_STRING
469
470       This variable holds a boolean indicating if we currently have
471       "IO::String" support loaded. This will be enabled for any perl that has
472       a loadable "IO::String" module.
473
474       If you feel strongly about disabling it, set this variable to "false".
475       Note that you will then need "perlio" support from your perl to be able
476       to  write stringified archives.
477
478       Don't change this variable unless you really know what you're doing.
479

FAQ

481       What's the minimum perl version required to run Archive::Tar?
482           You will need perl version 5.005_03 or newer.
483
484       Isn't Archive::Tar slow?
485           Yes it is. It's pure perl, so it's a lot slower then your
486           "/bin/tar" However, it's very portable. If speed is an issue, con‐
487           sider using "/bin/tar" instead.
488
489       Isn't Archive::Tar heavier on memory than /bin/tar?
490           Yes it is, see previous answer. Since "Compress::Zlib" and there‐
491           fore "IO::Zlib" doesn't support "seek" on their filehandles, there
492           is little choice but to read the archive into memory.  This is ok
493           if you want to do in-memory manipulation of the archive.  If you
494           just want to extract, use the "extract_archive" class method
495           instead. It will optimize and write to disk immediately.
496
497       Can't you lazy-load data instead?
498           No, not easily. See previous question.
499
500       How much memory will an X kb tar file need?
501           Probably more than X kb, since it will all be read into memory. If
502           this is a problem, and you don't need to do in memory manipulation
503           of the archive, consider using "/bin/tar" instead.
504
505       What do you do with unsupported filetypes in an archive?
506           "Unix" has a few filetypes that aren't supported on other plat‐
507           forms, like "Win32". If we encounter a "hardlink" or "symlink"
508           we'll just try to make a copy of the original file, rather than
509           throwing an error.
510
511           This does require you to read the entire archive in to memory
512           first, since otherwise we wouldn't know what data to fill the copy
513           with.  (This means that you cannot use the class methods on ar‐
514           chives that have incompatible filetypes and still expect things to
515           work).
516
517           For other filetypes, like "chardevs" and "blockdevs" we'll warn
518           that the extraction of this particular item didn't work.
519
520       I'm using WinZip, or some other non-POSIX client, and files are not
521       being extracted properly!
522           By default, "Archive::Tar" is in a completely POSIX-compatible
523           mode, which uses the POSIX-specification of "tar" to store files.
524           For paths greather than 100 characters, this is done using the
525           "POSIX header prefix". Non-POSIX-compatible clients may not support
526           this part of the specification, and may only support the "GNU
527           Extended Header" functionality. To facilitate those clients, you
528           can set the $Archive::Tar::DO_NOT_USE_PREFIX variable to "true".
529           See the "GLOBAL VARIABLES" section for details on this variable.
530
531       How do I extract only files that have property X from an archive?
532           Sometimes, you might not wish to extract a complete archive, just
533           the files that are relevant to you, based on some criteria.
534
535           You can do this by filtering a list of "Archive::Tar::File" objects
536           based on your criteria. For example, to extract only files that
537           have the string "foo" in their title, you would use:
538
539               $tar->extract(
540                   grep { $_->full_path =~ /foo/ } $tar->get_files
541               );
542
543           This way, you can filter on any attribute of the files in the ar‐
544           chive.  Consult the "Archive::Tar::File" documentation on how to
545           use these objects.
546
547       How do I access .tar.Z files?
548           The "Archive::Tar" module can optionally use "Compress::Zlib" (via
549           the "IO::Zlib" module) to access tar files that have been com‐
550           pressed with "gzip". Unfortunately tar files compressed with the
551           Unix "compress" utility cannot be read by "Compress::Zlib" and so
552           cannot be directly accesses by "Archive::Tar".
553
554           If the "uncompress" or "gunzip" programs are available, you can use
555           one of these workarounds to read ".tar.Z" files from "Archive::Tar"
556
557           Firstly with "uncompress"
558
559               use Archive::Tar;
560
561               open F, "uncompress -c $filename ⎪";
562               my $tar = Archive::Tar->new(*F);
563               ...
564
565           and this with "gunzip"
566
567               use Archive::Tar;
568
569               open F, "gunzip -c $filename ⎪";
570               my $tar = Archive::Tar->new(*F);
571               ...
572
573           Similarly, if the "compress" program is available, you can use this
574           to write a ".tar.Z" file
575
576               use Archive::Tar;
577               use IO::File;
578
579               my $fh = new IO::File "⎪ compress -c >$filename";
580               my $tar = Archive::Tar->new();
581               ...
582               $tar->write($fh);
583               $fh->close ;
584

TODO

586       Check if passed in handles are open for read/write
587           Currently I don't know of any portable pure perl way to do this.
588           Suggestions welcome.
589
590       Allow archives to be passed in as string
591           Currently, we only allow opened filehandles or filenames, but not
592           strings. The internals would need some reworking to facilitate
593           stringified archives.
594
595       Facilitate processing an opened filehandle of a compressed archive
596           Currently, we only support this if the filehandle is an IO::Zlib
597           object.  Environments, like apache, will present you with an opened
598           filehandle to an uploaded file, which might be a compressed ar‐
599           chive.
600

AUTHOR

621       This module by Jos Boumans <kane@cpan.org>.
622

ACKNOWLEDGEMENTS

624       Thanks to Sean Burke, Chris Nandor, Chip Salzenberg, Tim Heaney and
625       especially Andrew Savige for their help and suggestions.
626

COPYRIGHT

628       This module is copyright (c) 2002 Jos Boumans <kane@cpan.org>.  All
629       rights reserved.
630
631       This library is free software; you may redistribute and/or modify it
632       under the same terms as Perl itself.
633
634
635
636perl v5.8.8                       2006-08-01                   Archive::Tar(3)