# man > Archive::Tar

---
type: CommandReference
command: Archive::Tar
mode: perldoc
section: 3perl
source: perldoc
---

## Quick Reference

- `use Archive::Tar; my $tar = Archive::Tar->new(); $tar->read('archive.tgz'); $tar->extract();` — read and extract a compressed tar
- `$tar->add_files('file.pl', 'docs/README'); $tar->write('out.tar');` — add files and write plain tar
- `$tar->add_data('new.txt', 'content'); $tar->write('out.tgz', COMPRESS_GZIP);` — add data in memory and write gzip compressed
- `$tar->rename('old', 'new'); $tar->chown('/', 'root'); $tar->chmod('/tmp', 1777);` — modify metadata in memory
- `Archive::Tar->create_archive('out.tgz', COMPRESS_GZIP, @filelist);` — class method to create archive directly
- `Archive::Tar->extract_archive('in.tgz', 1);` — class method to extract archive directly
- `my $iter = Archive::Tar->iter('archive.tar.gz', 1, {filter => qr/\.pm$/}); while(my $f = $iter->()) { ... }` — iterate over files without loading all into memory

## Name

**Archive::Tar** — module for manipulations of tar archives

## Synopsis

perl
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
## Options

### Object Methods

- `Archive::Tar->new( [$file, $compressed] )` — Returns a new Tar object. If arguments given, calls `read()` automatically. Returns undef on failure.
- `$tar->read( $filename|$handle, [$compressed, {opt => 'val'}] )` — Read the given tar file into memory. Replaces previous content. Options: `limit` (max files to read), `filter` (regex to match file names), `md5` (return md5sum instead of data), `extract` (write to disk immediately). Returns number of files in scalar context, list of `Archive::Tar::File` objects in list context.
- `$tar->contains_file( $filename )` — Check if archive contains a file (exact match on full path). Returns true or false.
- `$tar->extract( [@filenames] )` — Write files matching names to disk, creating subdirectories as needed. If no list given, extracts all. Returns list of extracted filenames.
- `$tar->extract_file( $file, [$extract_path] )` — Write a single entry to disk. Optionally specify full native path. Returns true on success.
- `$tar->list_files( [\@properties] )` — Returns list of filenames. If passed array reference, returns list of hashrefs with requested properties: name, size, mtime, mode, uid, gid, linkname, uname, gname, devmajor, devminor, prefix. Special case: `['name']` returns list of names.
- `$tar->get_files( [@filenames] )` — Returns `Archive::Tar::File` objects matching filenames, or all objects if no list given.
- `$tar->get_content( $file )` — Return content of the named file.
- `$tar->replace_content( $file, $content )` — Replace content of a file in memory.
- `$tar->rename( $file, $new_name )` — Rename file in memory. $new_name must be Unix path. Returns true on success.
- `$tar->chmod( $file, $mode )` — Change mode of file. Returns true on success.
- `$tar->chown( $file, $uname [, $gname] )` — Change owner (and optionally group). Returns true on success.
- `$tar->remove( @filenamelist )` — Remove entries matching names. Returns list of remaining `Archive::Tar::File` objects.
- `$tar->clear` — Clear the in-memory archive (does not affect underlying tarfile).
- `$tar->write( [$file, $compressed, $prefix] )` — Write in-memory archive to disk. $file can be filename or filehandle reference. $compressed: use constants `COMPRESS_GZIP`, `COMPRESS_BZIP`, `COMPRESS_XZ` (or digit for gzip level). $prefix: directory to prepend to all file paths. If no arguments, returns formatted archive as string.
- `$tar->add_files( @filenamelist )` — Add files to in-memory archive. Paths converted to Unix equivalents. Returns list of added `Archive::Tar::File` objects.
- `$tar->add_data( $filename, $data, [$opthashref] )` — Add a file with given name and content. Options: name, size, mtime, mode, uid, gid, linkname, uname, gname, devmajor, devminor, prefix, type. Type constants: `FILE`, `HARDLINK`, `SYMLINK`, `CHARDEV`, `BLOCKDEV`, `DIR`, `FIFO`, `SOCKET`. Returns `Archive::Tar::File` object or undef on failure.
- `$tar->error( [$BOOL] )` — Returns current error string. If true argument, returns `Carp::longmess` stacktrace.
- `$tar->setcwd( $cwd )` — Set current working directory for performance (avoid repeated `Cwd::cwd()` calls). Pass `undef` to revert to default.

### Class Methods

- `Archive::Tar->create_archive( $file, $compressed, @filelist )` — Create tar file from list of files. $file can be filename or filehandle. $compressed: same as `write()`. Returns false on failure.
- `Archive::Tar->iter( $filename, [$compressed, {opt => $val}] )` — Returns iterator function that reads tar file without loading all in memory. Each call returns next `Archive::Tar::File` object. Options: same as `read()`. Example: `my $next = Archive::Tar->iter("example.tar.gz", 1, {filter => qr/\.pm$/}); while(my $f = $next->()) { ... }`
- `Archive::Tar->list_archive( $file, $compressed, [\@properties] )` — List files in archive. $file can be filename or filehandle. Returns list of filenames or list of hashrefs with properties: full_path, name, size, mtime, mode, uid, gid, linkname, uname, gname, devmajor, devminor, prefix, type. Special case: `['name']` returns list of names.
- `Archive::Tar->extract_archive( $file, $compressed )` — Extract contents of tar file. Returns list of extracted files, or false on failure.
- `$bool = Archive::Tar->has_io_string` — True if `IO::String` support loaded.
- `$bool = Archive::Tar->has_perlio` — True if perlio support loaded (perl ≥5.8 with perlio).
- `$bool = Archive::Tar->has_zlib_support` — True if can extract zlib compressed archives.
- `$bool = Archive::Tar->has_bzip2_support` — True if can extract bzip2 compressed archives.
- `$bool = Archive::Tar->has_xz_support` — True if can extract xz compressed archives.
- `$bool = Archive::Tar->can_handle_compressed_files` — Returns true if all required compression modules are available.

### Global Variables

- `$Archive::Tar::FOLLOW_SYMLINK` — Set to 1 to follow symlinks (copy file when extracting). Default 0.
- `$Archive::Tar::CHOWN` — Set to 0 to disable chown on extraction. Default 1.
- `$Archive::Tar::CHMOD` — Set to 0 to disable chmod on extraction. Default 1.
- `$Archive::Tar::SAME_PERMISSIONS` — When CHMOD enabled, controls whether to apply permissions as-is (root: 1, normal: 0) or filter setid bits and umask.
- `$Archive::Tar::DO_NOT_USE_PREFIX` — Set to 1 to use GNU Extended Header for long paths instead of POSIX prefix. Default 0.
- `$Archive::Tar::DEBUG` — Set to 1 for verbose `Carp::longmess` warnings. Default 0.
- `$Archive::Tar::WARN` — Set to 0 to suppress warnings. Default 1.
- `$Archive::Tar::error` — Holds last reported error (discouraged; use `$tar->error` instead).
- `$Archive::Tar::INSECURE_EXTRACT_MODE` — Set to true to allow extraction outside current working directory (security risk). Default false.
- `$Archive::Tar::HAS_PERLIO` — Boolean indicating perlio support. Disable by setting to false (requires `IO::String`).
- `$Archive::Tar::HAS_IO_STRING` — Boolean indicating `IO::String` support. Disable by setting to false (requires perlio).
- `$Archive::Tar::ZERO_PAD_NUMBERS` — Set to 1 to create zero-padded numbers for size, mtime, checksum (for busybox compatibility). Default 0 (space-padded).
- `$Archive::Tar::RESOLVE_SYMLINK` — Controls symlink resolution behaviour. Values: `none` (disable), `speed` (default, re-reads archive), `memory` (uses less memory). Also settable via `$ENV{PERL5_AT_RESOLVE_SYMLINK}`.

## Examples

**Read and extract a gzip compressed tar archive:**

perl
use Archive::Tar;
my $tar = Archive::Tar->new;
$tar->read('archive.tgz');
$tar->extract();
**Create a tar archive with compression:**

perl
use Archive::Tar;
Archive::Tar->create_archive('out.tgz', COMPRESS_GZIP, 'file1.txt', 'file2.txt');
**Iterate through files matching a filter, extract them:**

perl
use Archive::Tar;
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";
}
**Add data and write to a filehandle:**

perl
use Archive::Tar;
use IO::File;
my $fh = IO::File->new("| gzip -c >out.tgz");
my $tar = Archive::Tar->new;
$tar->add_data('file.txt', 'Hello');
$tar->write($fh);
$fh->close;
## See Also

- [GNU tar specification](http://www.gnu.org/software/tar/manual/tar.html)
- [PAX format specification](http://www.opengroup.org/onlinepubs/007904975/utilities/pax.html)
- [Comparison of GNU and POSIX tar standards](http://www.delorie.com/gnu/docs/tar/tar_114.html)
- [GNU tar intends to switch to POSIX compatibility](http://www.gnu.org/software/tar/manual/html_node/Formats.html)
- [Comparison between various tar implementations](http://gd.tuwien.ac.at/utils/archivers/star/README.otherbugs)
- `Archive::Tar::File` — documentation for tar file objects