archive::tar.3

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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 (.Sh), 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::Tar 3"
.TH Archive::Tar 3 "2007-12-18" "perl v5.10.0" "Perl Programmers Reference Guide"
.\" 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::Tar \- module for manipulations of tar archives
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use Archive::Tar;
\&    my $tar = Archive::Tar\->new;
\&
\&    $tar\->read(\*(Aqorigin.tgz\*(Aq,1);
\&    $tar\->extract();
\&
\&    $tar\->add_files(\*(Aqfile/foo.pl\*(Aq, \*(Aqdocs/README\*(Aq);
\&    $tar\->add_data(\*(Aqfile/baz.txt\*(Aq, \*(AqThis is the contents now\*(Aq);
\&
\&    $tar\->rename(\*(Aqoldname\*(Aq, \*(Aqnew/file/name\*(Aq);
\&
\&    $tar\->write(\*(Aqfiles.tar\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Archive::Tar provides an object oriented mechanism for handling tar
files.  It provides class methods for quick and easy files handling
while also allowing for the creation of tar file objects for custom
manipulation.  If you have the IO::Zlib module installed,
Archive::Tar will also support compressed or gzipped tar files.
.PP
An object of class Archive::Tar represents a .tar(.gz) archive full
of files and things.
.SH "Object Methods"
.IX Header "Object Methods"
.ie n .Sh "Archive::Tar\->new( [$file, $compressed] )"
.el .Sh "Archive::Tar\->new( [$file, \f(CW$compressed\fP] )"
.IX Subsection "Archive::Tar->new( [$file, $compressed] )"
Returns a new Tar object. If given any arguments, \f(CW\*(C`new()\*(C'\fR calls the
\&\f(CW\*(C`read()\*(C'\fR method automatically, passing on the arguments provided to
the \f(CW\*(C`read()\*(C'\fR method.
.PP
If \f(CW\*(C`new()\*(C'\fR is invoked with arguments and the \f(CW\*(C`read()\*(C'\fR method fails
for any reason, \f(CW\*(C`new()\*(C'\fR returns undef.
.ie n .Sh "$tar\fP\->read ( \f(CW$filename\fP|$handle, \f(CW$compressed, {opt => 'val'} )"
.el .Sh "\f(CW$tar\fP\->read ( \f(CW$filename\fP|$handle, \f(CW$compressed\fP, {opt => 'val'} )"
.IX Subsection "$tar->read ( $filename|$handle, $compressed, {opt => 'val'} )"
Read the given tar file into memory.
The first argument can either be the name of a file or a reference to
an already open filehandle (or an IO::Zlib object if it's compressed)
The second argument indicates whether the file referenced by the first
argument is compressed.
.PP
The \f(CW\*(C`read\*(C'\fR will \fIreplace\fR any previous content in \f(CW$tar\fR!
.PP
The second argument may be considered optional if IO::Zlib is
installed, since it will transparently Do The Right Thing.
Archive::Tar will warn if you try to pass a compressed file if
IO::Zlib is not available and simply return.
.PP
Note that you can currently \fBnot\fR pass a \f(CW\*(C`gzip\*(C'\fR compressed
filehandle, which is not opened with \f(CW\*(C`IO::Zlib\*(C'\fR, nor a string
containing the full archive information (either compressed or
uncompressed). These are worth while features, but not currently
implemented. See the \f(CW\*(C`TODO\*(C'\fR section.
.PP
The third argument can be a hash reference with options. Note that
all options are case-sensitive.
.IP "limit" 4
.IX Item "limit"
Do not read more than \f(CW\*(C`limit\*(C'\fR files. This is useful if you have
very big archives, and are only interested in the first few files.
.IP "extract" 4
.IX Item "extract"
If set to true, immediately extract entries when reading them. This
gives you the same memory break as the \f(CW\*(C`extract_archive\*(C'\fR function.
Note however that entries will not be read into memory, but written
straight to disk.
.PP
All files are stored internally as \f(CW\*(C`Archive::Tar::File\*(C'\fR objects.
Please consult the Archive::Tar::File documentation for details.
.PP
Returns the number of files read in scalar context, and a list of
\&\f(CW\*(C`Archive::Tar::File\*(C'\fR objects in list context.
.ie n .Sh "$tar\fP\->contains_file( \f(CW$filename )"
.el .Sh "\f(CW$tar\fP\->contains_file( \f(CW$filename\fP )"
.IX Subsection "$tar->contains_file( $filename )"
Check if the archive contains a certain file.
It will return true if the file is in the archive, false otherwise.
.PP
Note however, that this function does an exact match using \f(CW\*(C`eq\*(C'\fR
on the full path. So it cannot compensate for case-insensitive file\-
systems or compare 2 paths to see if they would point to the same
underlying file.
.ie n .Sh "$tar\->extract( [@filenames] )"
.el .Sh "\f(CW$tar\fP\->extract( [@filenames] )"
.IX Subsection "$tar->extract( [@filenames] )"
Write files whose names are equivalent to any of the names in
\&\f(CW@filenames\fR to disk, creating subdirectories as necessary. This
might not work too well under \s-1VMS\s0.
Under MacPerl, the file's modification time will be converted to the
MacOS zero of time, and appropriate conversions will be done to the
path.  However, the length of each element of the path is not
inspected to see whether it's longer than MacOS currently allows (32
characters).
.PP
If \f(CW\*(C`extract\*(C'\fR is called without a list of file names, the entire
contents of the archive are extracted.
.PP
Returns a list of filenames extracted.
.ie n .Sh "$tar\fP\->extract_file( \f(CW$file, [$extract_path] )"
.el .Sh "\f(CW$tar\fP\->extract_file( \f(CW$file\fP, [$extract_path] )"
.IX Subsection "$tar->extract_file( $file, [$extract_path] )"
Write an entry, whose name is equivalent to the file name provided to
disk. Optionally takes a second parameter, which is the full native
path (including filename) the entry will be written to.
.PP
For example:
.PP
.Vb 1
\&    $tar\->extract_file( \*(Aqname/in/archive\*(Aq, \*(Aqname/i/want/to/give/it\*(Aq );
\&
\&    $tar\->extract_file( $at_file_object,   \*(Aqname/i/want/to/give/it\*(Aq );
.Ve
.PP
Returns true on success, false on failure.
.ie n .Sh "$tar\->list_files( [\e@properties] )"
.el .Sh "\f(CW$tar\fP\->list_files( [\e@properties] )"
.IX Subsection "$tar->list_files( [@properties] )"
Returns a list of the names of all the files in the archive.
.PP
If \f(CW\*(C`list_files()\*(C'\fR is passed an array reference as its first argument
it returns a list of hash references containing the requested
properties of each file.  The following list of properties is
supported: name, size, mtime (last modified date), mode, uid, gid,
linkname, uname, gname, devmajor, devminor, prefix.
.PP
Passing an array reference containing only one element, 'name', is
special cased to return a list of names rather than a list of hash
references, making it equivalent to calling \f(CW\*(C`list_files\*(C'\fR without
arguments.
.ie n .Sh "$tar\->get_files( [@filenames] )"
.el .Sh "\f(CW$tar\fP\->get_files( [@filenames] )"
.IX Subsection "$tar->get_files( [@filenames] )"
Returns the \f(CW\*(C`Archive::Tar::File\*(C'\fR objects matching the filenames
provided. If no filename list was passed, all \f(CW\*(C`Archive::Tar::File\*(C'\fR
objects in the current Tar object are returned.
.PP
Please refer to the \f(CW\*(C`Archive::Tar::File\*(C'\fR documentation on how to
handle these objects.
.ie n .Sh "$tar\fP\->get_content( \f(CW$file )"
.el .Sh "\f(CW$tar\fP\->get_content( \f(CW$file\fP )"
.IX Subsection "$tar->get_content( $file )"
Return the content of the named file.
.ie n .Sh "$tar\fP\->replace_content( \f(CW$file\fP, \f(CW$content )"
.el .Sh "\f(CW$tar\fP\->replace_content( \f(CW$file\fP, \f(CW$content\fP )"
.IX Subsection "$tar->replace_content( $file, $content )"
Make the string \f(CW$content\fR be the content for the file named \f(CW$file\fR.
.ie n .Sh "$tar\fP\->rename( \f(CW$file\fP, \f(CW$new_name )"
.el .Sh "\f(CW$tar\fP\->rename( \f(CW$file\fP, \f(CW$new_name\fP )"
.IX Subsection "$tar->rename( $file, $new_name )"