/ 
Archive-Ar-2.02
River stage one • 2 direct dependents • 3 total dependents
/ Archive::Ar

NAME

Archive::Ar - Interface for manipulating ar archives

SYNOPSIS

use Archive::Ar;

my $ar = Archive::Ar->new;

$ar->read('./foo.ar');
$ar->extract;

$ar->add_files('./bar.tar.gz', 'bat.pl')
$ar->add_data('newfile.txt','Some contents');

$ar->chmod('file1', 0644);
$ar->chown('file1', $uid, $gid);

$ar->remove('file1', 'file2');

my $filehash = $ar->get_content('bar.tar.gz');
my $data = $ar->get_data('bar.tar.gz');
my $handle = $ar->get_handle('bar.tar.gz');

my @files = $ar->list_files();

my $archive = $ar->write;
my $size = $ar->write('outbound.ar');

$ar->error();

DESCRIPTION

Archive::Ar is a pure-perl way to handle standard ar archives.

This is useful if you have those types of archives on the system, but it is also useful because .deb packages for the Debian GNU/Linux distribution are ar archives. This is one building block in a future chain of modules to build, manipulate, extract, and test debian modules with no platform or architecture dependence.

You may notice that the API to Archive::Ar is similar to Archive::Tar, and this was done intentionally to keep similarity between the Archive::* modules.

METHODS

new

$ar = Archive::Ar->new()
$ar = Archive::Ar->new($filename)
$ar = Archive::Ar->new($filehandle)

Returns a new Archive::Ar object. Without an argument, it returns an empty object. If passed a filename or an open filehandle, it will read the referenced archive into memory. If the read fails for any reason, returns undef.

set_opt

$ar->set_opt($name, $val)

Assign option $name value $val. Possible options are:

  • warn

    Warning level. Levels are zero for no warnings, 1 for brief warnings, and 2 for warnings with a stack trace. Default is zero.

  • chmod

    Change the file permissions of files created when extracting. Default is true (non-zero).

  • same_perms

    When setting file permissions, use the values in the archive unchanged. If false, removes setuid bits and applies the user's umask. Default is true for the root user, false otherwise.

  • chown

    Change the owners of extracted files, if possible. Default is true.

  • type

    Archive type. May be GNU, BSD or COMMON, or undef if no archive has been read. Defaults to the type of the archive read, or undef.

  • symbols

    Provide a filename for the symbol table, if present. If set, the symbol table is treated as a file that can be read from or written to an archive. It is an error if the filename provided matches the name of a file in the archive. If undefined, the symbol table is ignored. Defaults to undef.

get_opt

$val = $ar->get_opt($name)

Returns the value of option $name.

type

$type = $ar->type()

Returns the type of the ar archive. The type is undefined until an archive is loaded. If the archive displays characteristics of a gnu-style archive, GNU is returned. If it looks like a bsd-style archive, BSD is returned. Otherwise, COMMON is returned. Note that unless filenames exceed 16 characters in length, bsd archives look like the common format.

clear

$ar->clear()

Clears the current in-memory archive.

read

$len = $ar->read($filename)
$len = $ar->read($filehandle)

This reads a new file into the object, removing any ar archive already represented in the object. The argument may be a filename, filehandle or IO::Handle object. Returns the size of the file contents or undef if it fails.

read_memory

$len = $ar->read_memory($data)

Parses the string argument as an archive, reading it into memory. Replaces any previously loaded archive. Returns the number of bytes read, or undef if it fails.

contains_file

$bool = $ar->contains_file($filename)

Returns true if the archive contains a file with $filename. Returns undef otherwise.

extract

$ar->extract()
$ar->extract_file($filename)

Extracts files from the archive. The first form extracts all files, the latter extracts just the named file. Extracted files are assigned the permissions and modification time stored in the archive, and, if possible, the user and group ownership. Returns non-zero upon success, or undef if failure.

rename

$ar->rename($filename, $newname)

Changes the name of a file in the in-memory archive.

chmod

$ar->chmod($filename, $mode);

Change the mode of the member to $mode.

chown

$ar->chown($filename, $uid, $gid);
$ar->chown($filename, $uid);

Change the ownership of the member to user id $uid and (optionally) group id $gid. Negative id values are ignored.

remove

$ar->remove(@filenames)
$ar->remove($arrayref)

Removes files from the in-memory archive. Returns the number of files removed.

list_files

@filenames = $ar->list_files()

Returns a list of the names of all the files in the archive. If called in a scalar context, returns a reference to an array.

add_files

$ar->add_files(@filenames)
$ar->add_files($arrayref)

Adds files to the archive. The arguments can be paths, but only the filenames are stored in the archive. Stores the uid, gid, mode, size, and modification timestamp of the file as returned by stat().

Returns the number of files successfully added, or undef if failure.

add_data

$ar->add_data("filename", $data)
$ar->add_data("filename", $data, $options)

Adds a file to the in-memory archive with name $filename and content $data. File properties can be set with $optional_hashref:

$options = {
    'data' => $data,
    'uid' => $uid,    #defaults to zero
    'gid' => $gid,    #defaults to zero
    'date' => $date,  #date in epoch seconds. Defaults to now.
    'mode' => $mode,  #defaults to 0100644;
}

You cannot add_data over another file however. This returns the file length in bytes if it is successful, undef otherwise.

write

$data = $ar->write()
$len = $ar->write($filename)

Returns the archive as a string, or writes it to disk as $filename. Returns the archive size upon success when writing to disk. Returns undef if failure.

get_content

$content = $ar->get_content($filename)

This returns a hash with the file content in it, including the data that the file would contain. If the file does not exist or no filename is given, this returns undef. On success, a hash is returned:

$content = {
    'name' => $filename,
    'date' => $mtime,
    'uid' => $uid,
    'gid' => $gid,
    'mode' => $mode,
    'size' => $size,
    'data' => $file_contents,
}

get_data

$data = $ar->get_data("filename")

Returns a scalar containing the file data of the given archive member. Upon error, returns undef.

get_handle

$handle = $ar->get_handle("filename")>

Returns a file handle to the in-memory file data of the given archive member. Upon error, returns undef. This can be useful for unpacking nested archives. Uses IO::String if it's loaded.

error

$errstr = $ar->error($trace)

Returns the current error string, which is usually the last error reported. If a true value is provided, returns the error message and stack trace.

BUGS

See https://github.com/jbazik/Archive-Ar/issues/ to report and view bugs.

SOURCE

The source code repository for Archive::Ar can be found at http://github.com/jbazik/Archive-Ar/.

COPYRIGHT

Copyright 2009-2014 John Bazik <jbazik@cpan.org>.

Copyright 2003 Jay Bonci <jaybonci@cpan.org>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html