Provided by: libarchive-ar-perl_1.15-1_all 
NAME
Archive::Ar - Interface for manipulating ar archives
SYNOPSIS
use Archive::Ar;
my $ar = new Archive::Ar("./foo.ar");
$ar->add_data("newfile.txt","Some contents", $properties);
$ar->add_files("./bar.tar.gz", "bat.pl")
$ar->add_files(["./again.gz"]);
$ar->remove("file1", "file2");
$ar->remove(["file1", "file2");
my $filedata = $ar->get_content("bar.tar.gz");
my @files = $ar->list_files();
$ar->read("foo.deb");
$ar->write("outbound.ar");
$ar->DEBUG();
DESCRIPTION
Archive::Ar is a pure-perl way to handle standard ar archives.
This is useful if you have those types of old 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
Class Methods
• "new()"
• "new($filename)"
• "new(*GLOB,$debug)"
Returns a new Archive::Ar object. Without a filename or glob, it returns an empty
object. If passed a filename as a scalar or in a GLOB, it will attempt to populate
from either of those sources. If it fails, you will receive undef, instead of an
object reference.
This also can take a second optional debugging parameter. This acts exactly as if
"DEBUG()" is called on the object before it is returned. If you have a "new()" that
keeps failing, this should help.
• "read($filename)"
• "read(*GLOB)";
This reads a new file into the object, removing any ar archive already represented in
the object. Any calls to "DEBUG()" are not lost by reading in a new file. Returns the
number of bytes read, undef on failure.
• "read_memory($data)"
This read information from the first parameter, and attempts to parse and treat it
like an ar archive. Like "read()", it will wipe out whatever you have in the object
and replace it with the contents of the new archive, even if it fails. Returns the
number of bytes read (processed) if successful, undef otherwise.
• "list_files()"
This lists the files contained inside of the archive by filename, as an array. If
called in a scalar context, returns a reference to an array.
• "add_files("filename1", "filename2")"
• "add_files(["filename1", "filename2"])"
Takes an array or an arrayref of filenames to add to the ar archive, in order. The
filenames can be paths to files, in which case the path information is stripped off.
Filenames longer than 16 characters are truncated when written to disk in the format,
so keep that in mind when adding files.
Due to the nature of the ar archive format, "add_files()" will store the uid, gid,
mode, size, and creation date of the file as returned by "stat()";
"add_files()" returns the number of files successfully added, or undef on failure.
• "add_data("filename", $filedata)"
Takes an filename and a set of data to represent it. Unlike "add_files", "add_data" is
a virtual add, and does not require data on disk to be present. The data is a hash
that looks like:
$filedata = {
"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()"
• "write("filename.ar")"
This method will return the data as an .ar archive, or will write to the filename
present if specified. If given a filename, "write()" will return the length of the
file written, in bytes, or undef on failure. If the filename already exists, it will
overwrite that file.
• "get_content("filename")"
This returns a hash with the file content in it, including the data that the file
would naturally contain. If the file does not exist or no filename is given, this
returns undef. On success, a hash is returned with the following keys:
name - The file name
date - The file date (in epoch seconds)
uid - The uid of the file
gid - The gid of the file
mode - The mode permissions
size - The size (in bytes) of the file
data - The contained data
• "remove("filename1", "filename2")"
• "remove(["filename1", "filename2"])"
The remove method takes a filenames as a list or as an arrayref, and removes them, one
at a time, from the Archive::Ar object. This returns the number of files successfully
removed from the archive.
• "DEBUG()"
This method turns on debugging. Optionally this can be done by passing in a value as
the second parameter to new. While verbosity is enabled, Archive::Ar will toss a
"warn()" if there is a suspicious condition or other problem while proceeding. This
should help iron out any problems you have while using the module.
CHANGES
• Version 1.15 - May 14, 2013
Use binmode for portability. Closes RT #81310 (thanks to Stanislav Meduna).
• Version 1.14 - October 14, 2009
Fix list_files to return a list in list context, to match doc.
Pad odd-size archives to an even number of bytes. Closes RT #18383 (thanks to David
Dick).
Fixed broken file perms (decimal mode stored as octal string). Closes RT #49987
(thanks to Stephen Gran - debian bug #523515).
• Version 1.13b - May 7th, 2003
Fixes to the Makefile.PL file. Ar.pm wasn't being put into /blib Style fix to a line
with non-standard unless parenthesis
• Version 1.13 - April 30th, 2003
Removed unneeded exports. Thanks to pudge for the pointer.
• Version 1.12 - April 14th, 2003
Found podchecker. CPAN HTML documentation should work right now.
• Version 1.11 - April 10th, 2003
Trying to get the HTML POD documentation to come out correctly
• Version 1.1 - April 10th, 2003
Documentation cleanups Added a "remove()" function
• Version 1.0 - April 7th, 2003
This is the initial public release for CPAN, so everything is new.
TODO
A better unit test suite perhaps. I have a private one, but a public one would be nice if
there was good file faking module.
Fix / investigate stuff in the BUGS section.
BUGS
To be honest, I'm not sure of a couple of things. The first is that I know of ar archives
made on old AIX systems (pre 4.3?) that have a different header with a different magic
string, etc. This module perfectly (hopefully) handles ar archives made with the modern
ar command from the binutils distribution. If anyone knows of anyway to produce these old-
style AIX archives, or would like to produce a few for testing, I would be much grateful.
There's no really good reason why this module shouldn't run on Win32 platforms, but
admittedly, this might change when we have a file exporting function that supports owner
and permission writing.
If you read in and write out a file, you get different md5sums, but it's still a valid
archive. I'm still investigating this, and consider it a minor bug.
COPYRIGHT
Archive::Ar is 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.