man > Archive::Tar

man perldoc info pydoc3 ri search

📖 NAME

Archive::Tar - module for manipulations of tar archives

🚀 Quick Reference

Use Case	Command	Description
📦 Create new tar object	my $tar = Archive::Tar->new;	Returns a new empty Tar object
📂 Read tar file	$tar->read('origin.tgz');	Read archive into memory (supports gz/bz2/xz)
📤 Extract all files	$tar->extract();	Extract entire archive to current directory
📄 Extract specific file	$tar->extract_file('file');	Extract a single entry by name
➕ Add files to archive	$tar->add_files('file.pl', 'docs/README');	Add existing files from disk
✏️ Add data as file	$tar->add_data('file.txt', 'content');	Add a file with inline data
🔄 Rename entry	$tar->rename('oldname', 'newname');	Rename a file inside the archive
📝 Change permissions	$tar->chmod('/tmp', '1777');	Change mode of an entry
👤 Change ownership	$tar->chown('/', 'root:root');	Change owner/group of an entry
💾 Write archive to file	$tar->write('files.tar');	Write uncompressed tar
📦 Write compressed	$tar->write('files.tgz', COMPRESS_GZIP);	Write gzip/bzip2/xz compressed (use constants)
📋 List files	$tar->list_files();	Return list of filenames
🔍 Check file existence	$tar->contains_file($filename);	True if file is in archive
🗑️ Remove files	$tar->remove(@filenames);	Remove entries from in-memory archive
🔄 Class method: create archive	Archive::Tar->create_archive('out.tgz', COMPRESS_GZIP, @filelist);	Directly create tar from file list
⏳ Iterate without loading	Archive::Tar->iter($filename, $compressed, \%opts);	Returns iterator over archive entries

📝 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 offers class methods for quick files handling and object creation for custom manipulation. If you have IO::Zlib installed, it also supports compressed/gzipped tar files.

🔧 Object Methods

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

Returns a new Tar object. With arguments, automatically calls read(). Returns undef if read() fails.

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

Read the given tar file into memory. Replaces any previous content. Looks at file magic to determine compression. Supports options:

• limit – Do not read more than limit files (useful for large archives).
• filter – Regex; only read files with matching names.
• md5 – Set to 1 to return md5sum instead of file data.
• extract – If true, immediately extract entries to disk without loading into memory.

Returns number of files read in scalar context, list of Archive::Tar::File objects in list context.

🔍 $tar->contains_file( $filename )

Check if the archive contains a file. Returns true if exists, false otherwise. Uses exact match (eq) on full path.

📤 $tar->extract( [@filenames] )

Write files matching names to disk, creating subdirectories as needed. Without arguments, extracts entire archive. Returns list of filenames extracted.

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

Write an entry to disk. Optionally specify a custom native 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 list of filenames. If passed an array reference of properties, returns list of hashrefs 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, or all objects if none given.

📄 $tar->get_content( $file )

Return the content of the named file as a scalar.

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

Replace the content of a file with the given string.

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

Rename an entry in the archive. Must use a Unix path. Returns true on success.

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

Change mode of an entry. Returns true on success.

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

Change owner/group of an entry. Returns true on success.

🗑️ $tar->remove (@filenamelist)

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

🧹 $tar->clear

Clear the current in-memory archive, giving a blank object ready to be filled again.

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

Write the in-memory archive to disk. First argument can be filename or open filehandle. Compression can be specified with constants: COMPRESS_GZIP, COMPRESS_BZIP, COMPRESS_XZ (or a digit 1-9 for gzip level). When using a filehandle, compression is ignored. Optional prefix nests all files under a directory.

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

Without arguments, returns the formatted archive as a string.

➕ $tar->add_files( @filenamelist )

Takes list of filenames and adds them to the archive. Paths are converted to Unix-like. On MacOS, modification time is converted. Accepts Archive::Tar::File objects (cloned). Returns list of added objects.

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

Add a file with given name and content. Properties can be set via hashref: name, size, mtime, mode, uid, gid, linkname, uname, gname, devmajor, devminor, prefix, type. Supported file types (constants from Archive::Tar::Constant):

• FILE – Regular file
• HARDLINK, SYMLINK – Hard and symbolic links (linkname required)
• CHARDEV, BLOCKDEV – Character and block devices (devmajor, devminor required)
• DIR – Directory
• FIFO – Named pipe
• SOCKET – Socket

Returns the Archive::Tar::File object added, or undef on failure.

⚠️ $tar->error( [$BOOL] )

Returns the current error string. If true argument, returns Carp::longmess stack trace. Also available as $Archive::Tar::error (discouraged).

📂 $tar->setcwd( $cwd );

Set the current working directory for extraction performance. Archive::Tar will use this cached value instead of calling Cwd::cwd() repeatedly. Pass undef to revert to default behavior. The extract() method calls this automatically.

🔧 Class Methods

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

Creates a tar file from a list of files. First argument can be filename or open filehandle. Compression constants: COMPRESS_GZIP, COMPRESS_BZIP, COMPRESS_XZ. Returns false on failure – use error() for details. Reads all files into memory before writing.

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

Returns an iterator function that reads the tar file without loading all into memory. Each call returns the next file as an Archive::Tar::File object or empty list when exhausted. Options identical to 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])

Returns list of filenames in the archive. Optional array reference of properties returns list of hashrefs. Supported properties: full_path, name, size, mtime, mode, uid, gid, linkname, uname, gname, devmajor, devminor, prefix, type.

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

Extracts contents of tar file. Returns list of extracted files, or false on failure.

🔍 $bool = Archive::Tar->has_io_string

Returns true if IO::String support is loaded.

🔍 $bool = Archive::Tar->has_perlio

Returns true if perlio support is loaded (requires perl 5.8+ with perlio).

🔍 $bool = Archive::Tar->has_zlib_support

Returns true if zlib compressed archives can be extracted.

🔍 $bool = Archive::Tar->has_bzip2_support

Returns true if bzip2 compressed archives can be extracted.

🔍 $bool = Archive::Tar->has_xz_support

Returns true if xz compressed archives can be extracted.

🔍 Archive::Tar->can_handle_compressed_files

Returns true if IO::Zlib, IO::Compress::Bzip2, and IO::Compress::Xz are available for on-the-fly decompression.

🌐 GLOBAL VARIABLES

$Archive::Tar::FOLLOW_SYMLINK

Set to 1 to copy symlinks when extracting (like /bin/tar -h). Default: 0 (keep symlink).

$Archive::Tar::CHOWN

Set to 0 to disable chown-ing files. Default: 1.

$Archive::Tar::CHMOD

Set to 0 to disable chmod-ing files. Default: 1.

$Archive::Tar::SAME_PERMISSIONS

When CHMOD enabled, controls whether to use archive permissions unmodified (root user default: 1) or filter setid bits and apply umask (normal users default: 0).

$Archive::Tar::DO_NOT_USE_PREFIX

Set to 1 to avoid POSIX prefix field for long paths (use GNU Extended Header instead). Default: 0. Useful for compatibility with older tar programs (Solaris, Irix, AIX).

$Archive::Tar::DEBUG

Set to 1 to get verbose Carp::longmess warnings. Default: 0.

$Archive::Tar::WARN

Set to 0 to suppress warnings. Default: 1. Not thread-safe.

$Archive::Tar::error

Holds last reported error (historical). Use $tar->error() method instead.

$Archive::Tar::INSECURE_EXTRACT_MODE

Set to true to allow extraction of files outside the current working directory (security risk). Default: false.

$Archive::Tar::HAS_PERLIO

Boolean indicating if perlio support is loaded. Disable by setting to false (requires IO::String as alternative).

$Archive::Tar::HAS_IO_STRING

Boolean indicating if IO::String support is loaded. Disable by setting to false (requires perlio support).

$Archive::Tar::ZERO_PAD_NUMBERS

Set to 1 to create zero-padded numbers for size, mtime, checksum (compatibility with busybox). Default: 0 (space padded).

Tuning the way RESOLVE_SYMLINK works

Set $Archive::Tar::RESOLVE_SYMLINK or $ENV{PERL5_AT_RESOLVE_SYMLINK} before loading the module. Values:

• none – Disable mechanism (fails like v < 1.88)
• speed (default) – Prefer speed: re-reads whole archive with read() so all entries available
• memory – Prefer memory

Limitation: Won't work for terminal, pipe, sockets, or non-seekable sources.

❓ FAQ

What's the minimum perl version?

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 it heavier on memory than /bin/tar?

Yes – it reads the entire archive into memory. For extraction only, use extract_archive() class method or iter() to stream.

Can you lazy-load data?

Yes, use iter() to iterate without loading all at once.

How much memory will an X kB tar file need?

More than X kB since it's all in memory. Use iter() or /bin/tar if this is a problem.

What do you do with unsupported filetypes?

For hardlinks/symlinks, we try to copy the original file (requires reading entire archive). For chardevs/blockdevs, we warn on extraction failure.

I'm using WinZip – files not extracting properly!

Set $Archive::Tar::DO_NOT_USE_PREFIX = 1 to use GNU Extended Header instead of POSIX prefix. GNU tar before 1.14 also has issues with POSIX prefix.

How do I extract only files with property X?

Filter Archive::Tar::File objects:

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

How do I access .tar.Z files?

Use uncompress or gunzip pipes:

open F, "uncompress -c $filename |";
my $tar = Archive::Tar->new(*F);

To write: open F, "| compress -c >$filename"; then $tar->write($fh);

How do I handle Unicode strings?

Add UTF-8 encoded bytes:

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

Extract and decode:

my $data = $tar->get_content();
$data = decode('utf8', $data);

⚠️ CAVEATS

AIX tar does not fill unused space with 0x00, causing "Invalid header block" warnings. Fixed in AIX 5.3 TL7 SP10, 5.3 TL8 SP8, 5.3 TL9 SP5, 5.3 TL10 SP2, 6.1 TL0 SP11, 6.1 TL1 SP7, 6.1 TL2 SP6, 6.1 TL3 SP3 (APAR IZ50240).

📋 TODO

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

🔗 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

Jos Boumans <kane AT cpan.org>. 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.

©️ COPYRIGHT

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