# man > Archive::Tar::File

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

## Quick Reference

- `Archive::Tar::File->new( file => $path )` — Create object from existing file
- `Archive::Tar::File->new( data => $path, $data, $opt )` — Create object from data with attributes
- `Archive::Tar::File->new( chunk => $chunk )` — Create object from raw tar chunk
- `$file->extract( [ $alternative_name ] )` — Extract file to disk
- `$file->get_content` — Get in-memory content
- `$file->replace_content( $content )` — Replace in-memory content
- `$file->rename( $new_name )` — Rename the file
- `$file->is_file` — Check if file type is regular file

## Name

Archive::Tar::File - a subclass for in-memory extracted file from Archive::Tar

## Synopsis

perl
my @items = $tar->get_files;
print $_->name, ' ', $_->size, "\n" for @items;

print $object->get_content;
$object->replace_content('new content');

$object->rename( 'new/full/path/to/file.c' );
## Options

### Accessors

- `name` — The file's name
- `mode` — The file's mode
- `uid` — The user id owning the file
- `gid` — The group id owning the file
- `size` — File size in bytes
- `mtime` — Modification time
- `chksum` — Checksum field for the tar header
- `type` — File type (numeric, comparable to exported constants)
- `linkname` — If the file is a symlink, the file it's pointing to
- `magic` — Tar magic string
- `version` — Tar version string
- `uname` — The user name that owns the file
- `gname` — The group name that owns the file
- `devmajor` — Device major number
- `devminor` — Device minor number
- `prefix` — Directory to prefix to extraction path
- `raw` — Raw tar header

### Methods

- `new( file => $path )` — Returns a new object from an existing file. Returns undef on failure.
- `new( data => $path, $data, $opt )` — Returns a new object from data. `$path` defines file name, `$data` contents, `$opt` reference to hash of attributes (overrides default accessors). Returns undef on failure.
- `new( chunk => $chunk )` — Returns a new object from a raw 512-byte tar archive chunk. Returns undef on failure.
- `extract( [ $alternative_name ] )` — Extract this object, optionally to an alternative name. See Archive::Tar::extract_file. Returns true on success, false on failure.
- `full_path` — Returns the full path from the tar header (concatenation of prefix and name).
- `validate` — Validate the header against the checksum. Returns true on success, false on failure.
- `has_content` — Returns a boolean indicating whether the object has content (some special files like directories never have content).
- `get_content` — Returns the current content for the in-memory file.
- `get_content_by_ref` — Returns the current content as a scalar reference (saves memory for large files).
- `replace_content( $content )` — Replace the current content of the file (in-memory only; not written to disk until archive is written). Returns true on success, false on failure.
- `rename( $new_name )` — Rename the file to `$new_name` (must be a Unix path). Returns true on success, false on failure.
- `chmod( $mode )` — Change mode of the file. `$mode` can be a string or number (interpreted as octal). Returns true on success, false on failure.
- `chown( $user [, $group] )` — Change owner to `$user` and optionally `$group`. Also accepts a single parameter with colon-separated user and group (e.g., 'root:wheel'). Returns true on success, false on failure.

### Convenience methods

- `is_file` — Returns true if file type is "file"
- `is_dir` — Returns true if file type is "dir"
- `is_hardlink` — Returns true if file type is "hardlink"
- `is_symlink` — Returns true if file type is "symlink"
- `is_chardev` — Returns true if file type is "chardev"
- `is_blockdev` — Returns true if file type is "blockdev"
- `is_fifo` — Returns true if file type is "fifo"
- `is_socket` — Returns true if file type is "socket"
- `is_longlink` — Returns true if file type is "LongLink"
- `is_label` — Returns true if file type is "Label"
- `is_unknown` — Returns true if file type is "unknown"

## Examples

perl
# Create an Archive::Tar::File object from an existing file
my $file = Archive::Tar::File->new( file => '/path/to/file.txt' );

# Create from data with custom attributes
my $file = Archive::Tar::File->new(
    data => 'myfile.txt',
    'some content',
    { mode => 0644, uid => 1000, gid => 1000 }
);

# Extract the file to disk
$file->extract('output.txt');

# Get and replace content
my $content = $file->get_content;
$file->replace_content('updated content');

# Rename the file
$file->rename('newdir/newname.txt');

# Check file type
if ($file->is_file) {
    print "It's a regular file\n";
}
## See Also

- [Archive::Tar](https://perldoc.perl.org/Archive::Tar) — module for handling tar archives

## Exit Codes

No exit codes are documented.