info > Archive::Tar

man perldoc info pydoc3 ri search

Archive::Tar(3perl) Perl Programmers Reference Guide Archive::Tar(3perl)

📛 NAME

Archive::Tar - module for manipulations of tar archives

🚀 Quick Reference

Use Case	Command	Description
🔧 Create a new tar object	my $tar = Archive::Tar->new('file.tgz')	Reads archive into memory, returns object or undef on failure
📖 Read an archive	$tar->read('file.tar', COMPRESS_GZIP, {filter=>qr/\.pm$/})	Load archive with optional compression and filtering
📂 Extract all files	$tar->extract()	Write all files to disk, creating subdirectories
📄 Extract specific files	$tar->extract('file1.txt', 'dir/file2.pl')	Extract only named files
➕ Add files to archive	$tar->add_files('file1', 'file2')	Add existing files by name
➕ Add data as file	$tar->add_data('new.txt', 'Hello World')	Add in-memory content as a file entry
💾 Write archive to disk	$tar->write('out.tgz', COMPRESS_GZIP, 'prefix')	Write with optional compression and prefix directory
🔍 List files	$tar->list_files([qw(name size mtime)])	Return names or hashrefs of properties
🔄 Iterate without loading all	my $next = Archive::Tar->iter('big.tar'); while (my $f = $next->()) { }	Memory-efficient streaming of archive entries
🏃 Quick extract (class method)	Archive::Tar->extract_archive('file.tgz', COMPRESS_GZIP)	Extract directly to disk, low memory
📋 Create archive (class method)	Archive::Tar->create_archive('out.tar', COMPRESS_GZIP, @files)	One-step archive creation from file list

📝 SYNOPSIS

use Archive::Tar;
my $tar = Archive::Tar->new;

$tar->read('origin.tgz');
$tar->extract();

$tar->add_files('file/foo.pl', 'docs/README');
$tar->add_data('file/baz.txt', 'This is the contents now');

$tar->rename('oldname', 'new/file/name');
$tar->chown('/', 'root');
$tar->chown('/', 'root:root');
$tar->chmod('/tmp', '1777');

$tar->write('files.tar');                   # plain tar
$tar->write('files.tgz', COMPRESS_GZIP);    # gzip compressed
$tar->write('files.tbz', COMPRESS_BZIP);    # bzip2 compressed
$tar->write('files.txz', COMPRESS_XZ);      # xz compressed

📖 DESCRIPTION

Archive::Tar provides an object oriented mechanism for handling tar files. It provides class methods for quick and easy files handling while also allowing for the creation of tar file objects for custom manipulation. If you have the IO::Zlib module installed, Archive::Tar will also support compressed or gzipped tar files.

An object of class Archive::Tar represents a .tar(.gz) archive full of files and things.

🔧 Object Methods

Archive::Tar->new( [$file, $compressed] )

Returns a new Tar object. If given any arguments, new() calls the read() method automatically. If new() is invoked with arguments and read() fails, new() returns undef.

$tar->read ( $filename|$handle, [$compressed, {opt => 'val'}] )

Read the given tar file into memory. The first argument can be a filename or a reference to an open filehandle (or an IO::Zlib object if compressed). The read replaces any previous content in $tar.

The second argument is optional; Archive::Tar now looks at file magic to determine compression. The third argument can be a hash reference with options:

• limit – Do not read more than limit files.
• filter – Regular expression; only files matching expression will be read.
• md5 – Set to 1 to return md5sum of files instead of data.
• extract – If true, immediately extract entries when reading (memory efficient).

Returns the number of files read (scalar) or a list of Archive::Tar::File objects (list).

$tar->contains_file( $filename )

Check if the archive contains a certain file (exact match on full path). Returns true/false.

$tar->extract( [@filenames] )

Write files matching names to disk, creating subdirectories as needed. If called without arguments, extract entire archive. Returns list of extracted filenames.

$tar->extract_file( $file, [$extract_path] )

Write a single entry to disk. Optionally specify a different path. Returns true on success.

$tar->extract_file( 'name/in/archive', 'name/i/want/to/give/it' );
$tar->extract_file( $at_file_object,   'name/i/want/to/give/it' );

$tar->list_files( [\@properties] )

Returns a list of all file names. If passed an array reference of properties, returns a list of hash references with those properties. Supported properties: name, size, mtime, mode, uid, gid, linkname, uname, gname, devmajor, devminor, prefix.

$tar->get_files( [@filenames] )

Returns Archive::Tar::File objects matching filenames. If no list, returns all objects.

$tar->get_content( $file )

Return the content of the named file.

$tar->replace_content( $file, $content )

Replace the content of a file entry.

$tar->rename( $file, $new_name )

Rename a file in the in-memory archive. Must use Unix path. Returns true/false.

$tar->chmod( $file, $mode )

Change mode of a file entry. Returns true/false.

$tar->chown( $file, $uname [, $gname] )

Change owner and group. Returns true/false.

$tar->remove (@filenamelist)

Remove entries matching filenames. Returns list of remaining Archive::Tar::File objects.

$tar->clear

Clear the in-memory archive, producing a blank object.

$tar->write ( [$file, $compressed, $prefix] )

Write the in-memory archive to disk. First argument can be filename or GLOB reference. Compression can be COMPRESS_GZIP, COMPRESS_BZIP, COMPRESS_XZ, or a digit (gzip level). The third argument is an optional prefix directory. If no arguments, returns the archive as a string.

# write a gzip compressed file
$tar->write( 'out.tgz', COMPRESS_GZIP );

# write a bzip compressed file
$tar->write( 'out.tbz', COMPRESS_BZIP );

# write a xz compressed file
$tar->write( 'out.txz', COMPRESS_XZ );

$tar->add_files( @filenamelist )

Add files to the in-memory archive by name. Unix path conversion is automatic. Returns list of added Archive::Tar::File objects.

$tar->add_data ( $filename, $data, [$opthashref] )

Add a file with given name and content. Optional hash reference can set properties: name, size, mtime, mode, uid, gid, linkname, uname, gname, devmajor, devminor, prefix, type. Constants for type: FILE, HARDLINK, SYMLINK, CHARDEV, BLOCKDEV, DIR, FIFO, SOCKET. Returns the Archive::Tar::File object or undef on failure.

$tar->error( [$BOOL] )

Returns the current error string. If true argument, returns stacktrace via Carp::longmess. Also available as $Archive::Tar::error (deprecated).

$tar->setcwd( $cwd )

Set the current working directory for extraction to avoid repeated Cwd::cwd() calls. Pass undef to revert to default behavior. The extract() method calls this automatically.

🏛️ Class Methods

Archive::Tar->create_archive($file, $compressed, @filelist)

Create a tar file from list of files. First argument can be filename or GLOB. Compression constants as above. Returns false on failure.

# write a gzip compressed file
Archive::Tar->create_archive( 'out.tgz', COMPRESS_GZIP, @filelist );

# write a bzip compressed file
Archive::Tar->create_archive( 'out.tbz', COMPRESS_BZIP, @filelist );

# write a xz compressed file
Archive::Tar->create_archive( 'out.txz', COMPRESS_XZ, @filelist );

Archive::Tar->iter( $filename, [ $compressed, {opt => $val} ] )

Returns an iterator function that reads the tar file without loading all in memory. Each call returns the next Archive::Tar::File object. Options same as read().

my $next = Archive::Tar->iter( "example.tar.gz", 1, {filter => qr/\.pm$/} );
while( my $f = $next->() ) {
    print $f->name, "\n";
    $f->extract or warn "Extraction failed";
}

Archive::Tar->list_archive($file, $compressed, [\@properties])

List files in an archive. Returns names or hash references with properties (same as object method).

Archive::Tar->extract_archive($file, $compressed)

Extract contents of a tar file to the current working directory. Returns list of extracted files or false on failure.

Support checks

• Archive::Tar->has_io_string – Returns true if IO::String support is loaded.
• Archive::Tar->has_perlio – Returns true if perlio support is loaded (perl 5.8+).
• Archive::Tar->has_zlib_support – Returns true if zlib compressed archives can be extracted.
• Archive::Tar->has_bzip2_support – Returns true if bzip2 compressed archives can be extracted.
• Archive::Tar->has_xz_support – Returns true if xz compressed archives can be extracted.
• Archive::Tar->can_handle_compressed_files – Returns true if all compression backends are available.

🌐 GLOBAL VARIABLES

These variables control the behavior of Archive::Tar. Set them before use.

• $Archive::Tar::FOLLOW_SYMLINK – Set to 1 to copy symlink targets (like tar -h). Default: 0.
• $Archive::Tar::CHOWN – Set to 0 to disable chown-ing. Default: 1.
• $Archive::Tar::CHMOD – Set to 0 to disable chmod-ing. Default: 1.
• $Archive::Tar::SAME_PERMISSIONS – When CHMOD is enabled, controls permission filtering. Default: 1 for root, 0 for normal users.
• $Archive::Tar::DO_NOT_USE_PREFIX – Set to 1 to use GNU Extended Headers instead of POSIX header prefix for long paths. Default: 0.
• $Archive::Tar::DEBUG – Set to 1 to get verbose error messages. Default: 0.
• $Archive::Tar::WARN – Set to 0 to suppress warnings. Default: 1.
• $Archive::Tar::error – Holds last error (deprecated; use $tar->error()).
• $Archive::Tar::INSECURE_EXTRACT_MODE – Set to true to allow extraction outside current directory. Default: 0 (security).
• $Archive::Tar::HAS_PERLIO – Boolean; set to false to disable perlio.
• $Archive::Tar::HAS_IO_STRING – Boolean; set to false to disable IO::String.
• $Archive::Tar::ZERO_PAD_NUMBERS – Set to 1 to zero-pad size/mtime/checksum (for busybox compatibility). Default: 0.

🔧 Tuning RESOLVE_SYMLINK

Behavior can be tuned by setting $Archive::Tar::RESOLVE_SYMLINK or environment variable PERL5_AT_RESOLVE_SYMLINK before loading the module.

• none – Disable (like version <1.88).
• speed (default) – Re-reads entire archive with read() for speed.
• memory – Prefer memory efficiency.

Limitation: Does not work for non-seekable sources (terminals, pipes, sockets).

❓ FAQ

• What's the minimum perl version required to run Archive::Tar? – You need perl 5.005_03 or newer.
• Isn't Archive::Tar slow? – Yes, it's pure perl. Use /bin/tar if speed is critical.
• Isn't Archive::Tar heavier on memory than /bin/tar? – Yes. Use extract_archive or iter for low memory.
• Can you lazy-load data instead? – Yes, use iter class method.
• How much memory will an X kb tar file need? – Probably more than X kb. Use iter or /bin/tar if memory is a concern.
• What do you do with unsupported filetypes in an archive? – For hardlinks/symlinks we try to copy the original file. For char/block devices we warn.
• I'm using WinZip, or some other non-POSIX client, and files are not being extracted properly! – Set $Archive::Tar::DO_NOT_USE_PREFIX to true. GNU tar before 1.14 also has issues.
• How do I extract only files that have property X from an archive? – Filter Archive::Tar::File objects:

$tar->extract(
    grep { $_->full_path =~ /foo/ } $tar->get_files
);

• How do I access .tar.Z files? – Use pipes to uncompress or gunzip, or compress for writing.
• How do I handle Unicode strings? – Encode to UTF-8 before adding, decode after extracting:

use Encode;
my $data = "Euro: \x{20AC}";
$data = encode('utf8', $data);
$tar->add_data('file.txt', $data);

# When extracting:
my $data = $tar->get_content();
$data = decode('utf8', $data);

⚠️ CAVEATS

The AIX tar does not fill unused space with 0x00, causing warnings like "Invalid header block at offset nnn". Fixed in AIX levels listed below (2009Q4). IBM APAR IZ50240.

• AIX 5.3 TL7 SP10, TL8 SP8, TL9 SP5, TL10 SP2
• AIX 6.1 TL0 SP11, TL1 SP7, TL2 SP6, TL3 SP3

📋 TODO

• Check if passed handles are open for read/write (pure perl solution unknown).
• Allow archives to be passed in as strings.
• Facilitate processing an opened filehandle of a compressed archive (currently only IO::Zlib).

🔗 SEE ALSO

• The GNU tar specification
• The PAX format specification
• A comparison of GNU and POSIX tar standards
• GNU Tar intends to switch to POSIX compatibility
• A Comparison between various tar implementations

👤 AUTHOR

This module by Jos Boumans <kane AT cpan.org>. Please report bugs to <bug-archive-tar AT rt.org>.

🙏 ACKNOWLEDGEMENTS

Thanks to Sean Burke, Chris Nandor, Chip Salzenberg, Tim Heaney, Gisle Aas, Rainer Tammer and especially Andrew Savige for their help and suggestions.

©️ COPYRIGHT

This module is copyright (c) 2002 - 2009 Jos Boumans <kane AT cpan.org>. All rights reserved. This library is free software; you may redistribute and/or modify it under the same terms as Perl itself.

📛 NAME 🚀 Quick Reference 📝 SYNOPSIS 📖 DESCRIPTION 🌐 GLOBAL VARIABLES ❓ FAQ ⚠️ CAVEATS 📋 TODO 🔗 SEE ALSO 👤 AUTHOR 🙏 ACKNOWLEDGEMENTS ©️ COPYRIGHT