oracular (3) Archive::Ar.3pm.gz
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