.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Archive::Ar 3pm"
.TH Archive::Ar 3pm "2009-10-14" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Archive::Ar \- Interface for manipulating ar archives
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        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();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Archive::Ar is a pure-perl way to handle standard ar archives.
.PP
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.
.PP
You may notice that the \s-1API\s0 to Archive::Ar is similar to Archive::Tar, and
this was done intentionally to keep similarity between the Archive::*
modules
.SS "Class Methods"
.IX Subsection "Class Methods"
.IP "\(bu" 4
\&\f(CW\*(C`new()\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`new(\f(CI$filename\f(CW)\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`new(\f(CI*GLOB\f(CW,\f(CI$debug\f(CW)\*(C'\fR
.Sp
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 \s-1GLOB\s0, it will attempt
to populate from either of those sources.  If it fails, you will receive 
undef, instead of an object reference.
.Sp
This also can take a second optional debugging parameter.  This acts exactly
as if \f(CW\*(C`DEBUG()\*(C'\fR is called on the object before it is returned.  If you have a
\&\f(CW\*(C`new()\*(C'\fR that keeps failing, this should help.
.IP "\(bu" 4
\&\f(CW\*(C`read(\f(CI$filename\f(CW)\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`read(\f(CI*GLOB\f(CW)\*(C'\fR;
.Sp
This reads a new file into the object, removing any ar archive already
represented in the object.  Any calls to \f(CW\*(C`DEBUG()\*(C'\fR are not lost by reading
in a new file. Returns the number of bytes read, undef on failure.
.IP "\(bu" 4
\&\f(CW\*(C`read_memory(\f(CI$data\f(CW)\*(C'\fR
.Sp
This read information from the first parameter, and attempts to parse and treat
it like an ar archive. Like \f(CW\*(C`read()\*(C'\fR, 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.
.IP "\(bu" 4
\&\f(CW\*(C`list_files()\*(C'\fR
.Sp
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.
.IP "\(bu" 4
\&\f(CW\*(C`add_files(\f(CI"filename1"\f(CW, \f(CI"filename2"\f(CW)\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`add_files(\f(CI["filename1", "filename2"]\f(CW)\*(C'\fR
.Sp
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.
.Sp
Due to the nature of the ar archive format, \f(CW\*(C`add_files()\*(C'\fR will store the uid,
gid, mode, size, and creation date of the file as returned by \f(CW\*(C`stat()\*(C'\fR;
.Sp
\&\f(CW\*(C`add_files()\*(C'\fR returns the number of files successfully added, or undef on failure.
.IP "\(bu" 4
\&\f(CW\*(C`add_data(\f(CI"filename"\f(CW, \f(CI$filedata\f(CW)\*(C'\fR
.Sp
Takes an filename and a set of data to represent it. Unlike \f(CW\*(C`add_files\*(C'\fR, \f(CW\*(C`add_data\*(C'\fR
is a virtual add, and does not require data on disk to be present. The
data is a hash that looks like:
.Sp
.Vb 7
\&        $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;
\&        }
.Ve
.Sp
You cannot add_data over another file however.  This returns the file length in 
bytes if it is successful, undef otherwise.
.IP "\(bu" 4
\&\f(CW\*(C`write()\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`write(\f(CI"filename.ar"\f(CW)\*(C'\fR
.Sp
This method will return the data as an .ar archive, or will write to the 
filename present if specified.  If given a filename, \f(CW\*(C`write()\*(C'\fR will return the 
length of the file written, in bytes, or undef on failure.  If the filename
already exists, it will overwrite that file.
.IP "\(bu" 4
\&\f(CW\*(C`get_content(\f(CI"filename"\f(CW)\*(C'\fR
.Sp
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:
.Sp
.Vb 7
\&        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
.Ve
.IP "\(bu" 4
\&\f(CW\*(C`remove(\f(CI"filename1"\f(CW, \f(CI"filename2"\f(CW)\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`remove(\f(CI["filename1", "filename2"]\f(CW)\*(C'\fR
.Sp
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.
.IP "\(bu" 4
\&\f(CW\*(C`DEBUG()\*(C'\fR
.Sp
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 \f(CW\*(C`warn()\*(C'\fR if there is a suspicious condition or other 
problem while proceeding. This should help iron out any problems you have
while using the module.
.SH "CHANGES"
.IX Header "CHANGES"
.IP "\(bu" 4
\&\fBVersion 1.14\fR \- October 14, 2009
.Sp
Fix list_files to return a list in list context, to match doc.
.Sp
Pad odd-size archives to an even number of bytes.
Closes \s-1RT\s0 #18383 (thanks to David Dick).
.Sp
Fixed broken file perms (decimal mode stored as octal string).
Closes \s-1RT\s0 #49987 (thanks to Stephen Gran \- debian bug #523515).
.IP "\(bu" 4
\&\fBVersion 1.13b\fR \- May 7th, 2003
.Sp
Fixes to the Makefile.PL file. Ar.pm wasn't being put into /blib
Style fix to a line with non-standard unless parenthesis
.IP "\(bu" 4
\&\fBVersion 1.13\fR \- April 30th, 2003
.Sp
Removed unneeded exports. Thanks to pudge for the pointer.
.IP "\(bu" 4
\&\fBVersion 1.12\fR \- April 14th, 2003
.Sp
Found podchecker. \s-1CPAN\s0 \s-1HTML\s0 documentation should work right now.
.IP "\(bu" 4
\&\fBVersion 1.11\fR \- April 10th, 2003
.Sp
Trying to get the \s-1HTML\s0 \s-1POD\s0 documentation to come out correctly
.IP "\(bu" 4
\&\fBVersion 1.1\fR \- April 10th, 2003
.Sp
Documentation cleanups
Added a \f(CW\*(C`remove()\*(C'\fR function
.IP "\(bu" 4
\&\fBVersion 1.0\fR \- April 7th, 2003
.Sp
This is the initial public release for \s-1CPAN\s0, so everything is new.
.SH "TODO"
.IX Header "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.
.PP
Fix / investigate stuff in the \s-1BUGS\s0 section.
.SH "BUGS"
.IX Header "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 \s-1AIX\s0 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 \s-1AIX\s0 archives, or would like
to produce a few for testing, I would be much grateful.
.PP
There's no really good reason why this module \fIshouldn't\fR run on Win32 
platforms, but admittedly, this might change when we have a file exporting 
function that supports owner and permission writing.
.PP
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.
.SH "COPYRIGHT"
.IX Header "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.