local-lib5/man/man3/Archive::Tar::File.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Archive::Tar::File 3"
 132 .TH Archive::Tar::File 3 "2009-09-10" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Archive::Tar::File \- a subclass for in\-memory extracted file from Archive::Tar
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&    my @items = $tar\->get_files;
 139 .Ve
 140 .PP
 141 .Vb 1
 142 \&    print $_\->name, ' ', $_\->size, "\en" for @items;
 143 .Ve
 144 .PP
 145 .Vb 2
 146 \&    print $object\->get_content;
 147 \&    $object\->replace_content('new content');
 148 .Ve
 149 .PP
 150 .Vb 1
 151 \&    $object\->rename( 'new/full/path/to/file.c' );
 152 .Ve
 153 .SH "DESCRIPTION"
 154 .IX Header "DESCRIPTION"
 155 Archive::Tar::Files provides a neat little object layer for in-memory
 156 extracted files. It's mostly used internally in Archive::Tar to tidy
 157 up the code, but there's no reason users shouldn't use this \s-1API\s0 as
 158 well.
 159 .Sh "Accessors"
 160 .IX Subsection "Accessors"
 161 A lot of the methods in this package are accessors to the various
 162 fields in the tar header:
 163 .IP "name" 4
 164 .IX Item "name"
 165 The file's name
 166 .IP "mode" 4
 167 .IX Item "mode"
 168 The file's mode
 169 .IP "uid" 4
 170 .IX Item "uid"
 171 The user id owning the file
 172 .IP "gid" 4
 173 .IX Item "gid"
 174 The group id owning the file
 175 .IP "size" 4
 176 .IX Item "size"
 177 File size in bytes
 178 .IP "mtime" 4
 179 .IX Item "mtime"
 180 Modification time. Adjusted to mac-time on MacOS if required
 181 .IP "chksum" 4
 182 .IX Item "chksum"
 183 Checksum field for the tar header
 184 .IP "type" 4
 185 .IX Item "type"
 186 File type \*(-- numeric, but comparable to exported constants \*(-- see
 187 Archive::Tar's documentation
 188 .IP "linkname" 4
 189 .IX Item "linkname"
 190 If the file is a symlink, the file it's pointing to
 191 .IP "magic" 4
 192 .IX Item "magic"
 193 Tar magic string \*(-- not useful for most users
 194 .IP "version" 4
 195 .IX Item "version"
 196 Tar version string \*(-- not useful for most users
 197 .IP "uname" 4
 198 .IX Item "uname"
 199 The user name that owns the file
 200 .IP "gname" 4
 201 .IX Item "gname"
 202 The group name that owns the file
 203 .IP "devmajor" 4
 204 .IX Item "devmajor"
 205 Device major number in case of a special file
 206 .IP "devminor" 4
 207 .IX Item "devminor"
 208 Device minor number in case of a special file
 209 .IP "prefix" 4
 210 .IX Item "prefix"
 211 Any directory to prefix to the extraction path, if any
 212 .IP "raw" 4
 213 .IX Item "raw"
 214 Raw tar header \*(-- not useful for most users
 215 .SH "Methods"
 216 .IX Header "Methods"
 217 .ie n .Sh "Archive::Tar::File\->new( file => $path )"
 218 .el .Sh "Archive::Tar::File\->new( file => \f(CW$path\fP )"
 219 .IX Subsection "Archive::Tar::File->new( file => $path )"
 220 Returns a new Archive::Tar::File object from an existing file.
 221 .PP
 222 Returns undef on failure.
 223 .ie n .Sh "Archive::Tar::File\->new( data => $path\fP, \f(CW$data\fP, \f(CW$opt )"
 224 .el .Sh "Archive::Tar::File\->new( data => \f(CW$path\fP, \f(CW$data\fP, \f(CW$opt\fP )"
 225 .IX Subsection "Archive::Tar::File->new( data => $path, $data, $opt )"
 226 Returns a new Archive::Tar::File object from data.
 227 .PP
 228 \&\f(CW$path\fR defines the file name (which need not exist), \f(CW$data\fR the
 229 file contents, and \f(CW$opt\fR is a reference to a hash of attributes
 230 which may be used to override the default attributes (fields in the
 231 tar header), which are described above in the Accessors section.
 232 .PP
 233 Returns undef on failure.
 234 .ie n .Sh "Archive::Tar::File\->new( chunk => $chunk )"
 235 .el .Sh "Archive::Tar::File\->new( chunk => \f(CW$chunk\fP )"
 236 .IX Subsection "Archive::Tar::File->new( chunk => $chunk )"
 237 Returns a new Archive::Tar::File object from a raw 512\-byte tar
 238 archive chunk.
 239 .PP
 240 Returns undef on failure.
 241 .ie n .Sh "$bool = $file\fP\->extract( [ \f(CW$alternative_name ] )"
 242 .el .Sh "$bool = \f(CW$file\fP\->extract( [ \f(CW$alternative_name\fP ] )"
 243 .IX Subsection "$bool = $file->extract( [ $alternative_name ] )"
 244 Extract this object, optionally to an alternative name.
 245 .PP
 246 See \f(CW\*(C`Archive::Tar\->extract_file\*(C'\fR for details.
 247 .PP
 248 Returns true on success and false on failure.
 249 .ie n .Sh "$path = $file\->full_path"
 250 .el .Sh "$path = \f(CW$file\fP\->full_path"
 251 .IX Subsection "$path = $file->full_path"
 252 Returns the full path from the tar header; this is basically a
 253 concatenation of the \f(CW\*(C`prefix\*(C'\fR and \f(CW\*(C`name\*(C'\fR fields.
 254 .ie n .Sh "$bool = $file\->validate"
 255 .el .Sh "$bool = \f(CW$file\fP\->validate"
 256 .IX Subsection "$bool = $file->validate"
 257 Done by Archive::Tar internally when reading the tar file:
 258 validate the header against the checksum to ensure integer tar file.
 259 .PP
 260 Returns true on success, false on failure
 261 .ie n .Sh "$bool = $file\->has_content"
 262 .el .Sh "$bool = \f(CW$file\fP\->has_content"
 263 .IX Subsection "$bool = $file->has_content"
 264 Returns a boolean to indicate whether the current object has content.
 265 Some special files like directories and so on never will have any
 266 content. This method is mainly to make sure you don't get warnings
 267 for using uninitialized values when looking at an object's content.
 268 .ie n .Sh "$content = $file\->get_content"
 269 .el .Sh "$content = \f(CW$file\fP\->get_content"
 270 .IX Subsection "$content = $file->get_content"
 271 Returns the current content for the in-memory file
 272 .ie n .Sh "$cref = $file\->get_content_by_ref"
 273 .el .Sh "$cref = \f(CW$file\fP\->get_content_by_ref"
 274 .IX Subsection "$cref = $file->get_content_by_ref"
 275 Returns the current content for the in-memory file as a scalar
 276 reference. Normal users won't need this, but it will save memory if
 277 you are dealing with very large data files in your tar archive, since
 278 it will pass the contents by reference, rather than make a copy of it
 279 first.
 280 .ie n .Sh "$bool = $file\fP\->replace_content( \f(CW$content )"
 281 .el .Sh "$bool = \f(CW$file\fP\->replace_content( \f(CW$content\fP )"
 282 .IX Subsection "$bool = $file->replace_content( $content )"
 283 Replace the current content of the file with the new content. This
 284 only affects the in-memory archive, not the on-disk version until
 285 you write it.
 286 .PP
 287 Returns true on success, false on failure.
 288 .ie n .Sh "$bool = $file\fP\->rename( \f(CW$new_name )"
 289 .el .Sh "$bool = \f(CW$file\fP\->rename( \f(CW$new_name\fP )"
 290 .IX Subsection "$bool = $file->rename( $new_name )"
 291 Rename the current file to \f(CW$new_name\fR.
 292 .PP
 293 Note that you must specify a Unix path for \f(CW$new_name\fR, since per tar
 294 standard, all files in the archive must be Unix paths.
 295 .PP
 296 Returns true on success and false on failure.
 297 .SH "Convenience methods"
 298 .IX Header "Convenience methods"
 299 To quickly check the type of a \f(CW\*(C`Archive::Tar::File\*(C'\fR object, you can
 300 use the following methods:
 301 .IP "$file\->is_file" 4
 302 .IX Item "$file->is_file"
 303 Returns true if the file is of type \f(CW\*(C`file\*(C'\fR
 304 .IP "$file\->is_dir" 4
 305 .IX Item "$file->is_dir"
 306 Returns true if the file is of type \f(CW\*(C`dir\*(C'\fR
 307 .IP "$file\->is_hardlink" 4
 308 .IX Item "$file->is_hardlink"
 309 Returns true if the file is of type \f(CW\*(C`hardlink\*(C'\fR
 310 .IP "$file\->is_symlink" 4
 311 .IX Item "$file->is_symlink"
 312 Returns true if the file is of type \f(CW\*(C`symlink\*(C'\fR
 313 .IP "$file\->is_chardev" 4
 314 .IX Item "$file->is_chardev"
 315 Returns true if the file is of type \f(CW\*(C`chardev\*(C'\fR
 316 .IP "$file\->is_blockdev" 4
 317 .IX Item "$file->is_blockdev"
 318 Returns true if the file is of type \f(CW\*(C`blockdev\*(C'\fR
 319 .IP "$file\->is_fifo" 4
 320 .IX Item "$file->is_fifo"
 321 Returns true if the file is of type \f(CW\*(C`fifo\*(C'\fR
 322 .IP "$file\->is_socket" 4
 323 .IX Item "$file->is_socket"
 324 Returns true if the file is of type \f(CW\*(C`socket\*(C'\fR
 325 .IP "$file\->is_longlink" 4
 326 .IX Item "$file->is_longlink"
 327 Returns true if the file is of type \f(CW\*(C`LongLink\*(C'\fR.
 328 Should not happen after a successful \f(CW\*(C`read\*(C'\fR.
 329 .IP "$file\->is_label" 4
 330 .IX Item "$file->is_label"
 331 Returns true if the file is of type \f(CW\*(C`Label\*(C'\fR.
 332 Should not happen after a successful \f(CW\*(C`read\*(C'\fR.
 333 .IP "$file\->is_unknown" 4
 334 .IX Item "$file->is_unknown"
 335 Returns true if the file type is \f(CW\*(C`unknown\*(C'\fR