Commit | Line | Data |
3fea05b9 |
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 3" |
132 | .TH Archive::Tar 3 "2009-09-10" "perl v5.8.7" "User Contributed Perl Documentation" |
133 | .SH "NAME" |
134 | Archive::Tar \- module for manipulations of tar archives |
135 | .SH "SYNOPSIS" |
136 | .IX Header "SYNOPSIS" |
137 | .Vb 2 |
138 | \& use Archive::Tar; |
139 | \& my $tar = Archive::Tar\->new; |
140 | .Ve |
141 | .PP |
142 | .Vb 2 |
143 | \& $tar\->read('origin.tgz'); |
144 | \& $tar\->extract(); |
145 | .Ve |
146 | .PP |
147 | .Vb 2 |
148 | \& $tar\->add_files('file/foo.pl', 'docs/README'); |
149 | \& $tar\->add_data('file/baz.txt', 'This is the contents now'); |
150 | .Ve |
151 | .PP |
152 | .Vb 1 |
153 | \& $tar\->rename('oldname', 'new/file/name'); |
154 | .Ve |
155 | .PP |
156 | .Vb 3 |
157 | \& $tar\->write('files.tar'); # plain tar |
158 | \& $tar\->write('files.tgz', COMPRESS_GZIP); # gzip compressed |
159 | \& $tar\->write('files.tbz', COMPRESS_BZIP); # bzip2 compressed |
160 | .Ve |
161 | .SH "DESCRIPTION" |
162 | .IX Header "DESCRIPTION" |
163 | Archive::Tar provides an object oriented mechanism for handling tar |
164 | files. It provides class methods for quick and easy files handling |
165 | while also allowing for the creation of tar file objects for custom |
166 | manipulation. If you have the IO::Zlib module installed, |
167 | Archive::Tar will also support compressed or gzipped tar files. |
168 | .PP |
169 | An object of class Archive::Tar represents a .tar(.gz) archive full |
170 | of files and things. |
171 | .SH "Object Methods" |
172 | .IX Header "Object Methods" |
173 | .ie n .Sh "Archive::Tar\->new( [$file, $compressed] )" |
174 | .el .Sh "Archive::Tar\->new( [$file, \f(CW$compressed\fP] )" |
175 | .IX Subsection "Archive::Tar->new( [$file, $compressed] )" |
176 | Returns a new Tar object. If given any arguments, \f(CW\*(C`new()\*(C'\fR calls the |
177 | \&\f(CW\*(C`read()\*(C'\fR method automatically, passing on the arguments provided to |
178 | the \f(CW\*(C`read()\*(C'\fR method. |
179 | .PP |
180 | If \f(CW\*(C`new()\*(C'\fR is invoked with arguments and the \f(CW\*(C`read()\*(C'\fR method fails |
181 | for any reason, \f(CW\*(C`new()\*(C'\fR returns undef. |
182 | .ie n .Sh "$tar\->read ( $filename|$handle, [$compressed, {opt => 'val'}] )" |
183 | .el .Sh "$tar\->read ( \f(CW$filename\fP|$handle, [$compressed, {opt => 'val'}] )" |
184 | .IX Subsection "$tar->read ( $filename|$handle, [$compressed, {opt => 'val'}] )" |
185 | Read the given tar file into memory. |
186 | The first argument can either be the name of a file or a reference to |
187 | an already open filehandle (or an IO::Zlib object if it's compressed) |
188 | .PP |
189 | The \f(CW\*(C`read\*(C'\fR will \fIreplace\fR any previous content in \f(CW$tar\fR! |
190 | .PP |
191 | The second argument may be considered optional, but remains for |
192 | backwards compatibility. Archive::Tar now looks at the file |
193 | magic to determine what class should be used to open the file |
194 | and will transparently Do The Right Thing. |
195 | .PP |
196 | Archive::Tar will warn if you try to pass a bzip2 compressed file and the |
197 | IO::Zlib / IO::Uncompress::Bunzip2 modules are not available and simply return. |
198 | .PP |
199 | Note that you can currently \fBnot\fR pass a \f(CW\*(C`gzip\*(C'\fR compressed |
200 | filehandle, which is not opened with \f(CW\*(C`IO::Zlib\*(C'\fR, a \f(CW\*(C`bzip2\*(C'\fR compressed |
201 | filehandle, which is not opened with \f(CW\*(C`IO::Uncompress::Bunzip2\*(C'\fR, nor a string |
202 | containing the full archive information (either compressed or |
203 | uncompressed). These are worth while features, but not currently |
204 | implemented. See the \f(CW\*(C`TODO\*(C'\fR section. |
205 | .PP |
206 | The third argument can be a hash reference with options. Note that |
207 | all options are case\-sensitive. |
208 | .IP "limit" 4 |
209 | .IX Item "limit" |
210 | Do not read more than \f(CW\*(C`limit\*(C'\fR files. This is useful if you have |
211 | very big archives, and are only interested in the first few files. |
212 | .IP "filter" 4 |
213 | .IX Item "filter" |
214 | Can be set to a regular expression. Only files with names that match |
215 | the expression will be read. |
216 | .IP "extract" 4 |
217 | .IX Item "extract" |
218 | If set to true, immediately extract entries when reading them. This |
219 | gives you the same memory break as the \f(CW\*(C`extract_archive\*(C'\fR function. |
220 | Note however that entries will not be read into memory, but written |
221 | straight to disk. This means no \f(CW\*(C`Archive::Tar::File\*(C'\fR objects are |
222 | created for you to inspect. |
223 | .PP |
224 | All files are stored internally as \f(CW\*(C`Archive::Tar::File\*(C'\fR objects. |
225 | Please consult the Archive::Tar::File documentation for details. |
226 | .PP |
227 | Returns the number of files read in scalar context, and a list of |
228 | \&\f(CW\*(C`Archive::Tar::File\*(C'\fR objects in list context. |
229 | .ie n .Sh "$tar\->contains_file( $filename )" |
230 | .el .Sh "$tar\->contains_file( \f(CW$filename\fP )" |
231 | .IX Subsection "$tar->contains_file( $filename )" |
232 | Check if the archive contains a certain file. |
233 | It will return true if the file is in the archive, false otherwise. |
234 | .PP |
235 | Note however, that this function does an exact match using \f(CW\*(C`eq\*(C'\fR |
236 | on the full path. So it cannot compensate for case-insensitive file\- |
237 | systems or compare 2 paths to see if they would point to the same |
238 | underlying file. |
239 | .Sh "$tar\->extract( [@filenames] )" |
240 | .IX Subsection "$tar->extract( [@filenames] )" |
241 | Write files whose names are equivalent to any of the names in |
242 | \&\f(CW@filenames\fR to disk, creating subdirectories as necessary. This |
243 | might not work too well under \s-1VMS\s0. |
244 | Under MacPerl, the file's modification time will be converted to the |
245 | MacOS zero of time, and appropriate conversions will be done to the |
246 | path. However, the length of each element of the path is not |
247 | inspected to see whether it's longer than MacOS currently allows (32 |
248 | characters). |
249 | .PP |
250 | If \f(CW\*(C`extract\*(C'\fR is called without a list of file names, the entire |
251 | contents of the archive are extracted. |
252 | .PP |
253 | Returns a list of filenames extracted. |
254 | .ie n .Sh "$tar\->extract_file( $file, [$extract_path] )" |
255 | .el .Sh "$tar\->extract_file( \f(CW$file\fP, [$extract_path] )" |
256 | .IX Subsection "$tar->extract_file( $file, [$extract_path] )" |
257 | Write an entry, whose name is equivalent to the file name provided to |
258 | disk. Optionally takes a second parameter, which is the full native |
259 | path (including filename) the entry will be written to. |
260 | .PP |
261 | For example: |
262 | .PP |
263 | .Vb 1 |
264 | \& $tar\->extract_file( 'name/in/archive', 'name/i/want/to/give/it' ); |
265 | .Ve |
266 | .PP |
267 | .Vb 1 |
268 | \& $tar\->extract_file( $at_file_object, 'name/i/want/to/give/it' ); |
269 | .Ve |
270 | .PP |
271 | Returns true on success, false on failure. |
272 | .Sh "$tar\->list_files( [\e@properties] )" |
273 | .IX Subsection "$tar->list_files( [@properties] )" |
274 | Returns a list of the names of all the files in the archive. |
275 | .PP |
276 | If \f(CW\*(C`list_files()\*(C'\fR is passed an array reference as its first argument |
277 | it returns a list of hash references containing the requested |
278 | properties of each file. The following list of properties is |
279 | supported: name, size, mtime (last modified date), mode, uid, gid, |
280 | linkname, uname, gname, devmajor, devminor, prefix. |
281 | .PP |
282 | Passing an array reference containing only one element, 'name', is |
283 | special cased to return a list of names rather than a list of hash |
284 | references, making it equivalent to calling \f(CW\*(C`list_files\*(C'\fR without |
285 | arguments. |
286 | .Sh "$tar\->get_files( [@filenames] )" |
287 | .IX Subsection "$tar->get_files( [@filenames] )" |
288 | Returns the \f(CW\*(C`Archive::Tar::File\*(C'\fR objects matching the filenames |
289 | provided. If no filename list was passed, all \f(CW\*(C`Archive::Tar::File\*(C'\fR |
290 | objects in the current Tar object are returned. |
291 | .PP |
292 | Please refer to the \f(CW\*(C`Archive::Tar::File\*(C'\fR documentation on how to |
293 | handle these objects. |
294 | .ie n .Sh "$tar\->get_content( $file )" |
295 | .el .Sh "$tar\->get_content( \f(CW$file\fP )" |
296 | .IX Subsection "$tar->get_content( $file )" |
297 | Return the content of the named file. |
298 | .ie n .Sh "$tar\->replace_content( $file\fP, \f(CW$content )" |
299 | .el .Sh "$tar\->replace_content( \f(CW$file\fP, \f(CW$content\fP )" |
300 | .IX Subsection "$tar->replace_content( $file, $content )" |
301 | Make the string \f(CW$content\fR be the content for the file named \f(CW$file\fR. |
302 | .ie n .Sh "$tar\->rename( $file\fP, \f(CW$new_name )" |
303 | .el .Sh "$tar\->rename( \f(CW$file\fP, \f(CW$new_name\fP )" |
304 | .IX Subsection "$tar->rename( $file, $new_name )" |
305 | Rename the file of the in-memory archive to \f(CW$new_name\fR. |
306 | .PP |
307 | Note that you must specify a Unix path for \f(CW$new_name\fR, since per tar |
308 | standard, all files in the archive must be Unix paths. |
309 | .PP |
310 | Returns true on success and false on failure. |
311 | .Sh "$tar\->remove (@filenamelist)" |
312 | .IX Subsection "$tar->remove (@filenamelist)" |
313 | Removes any entries with names matching any of the given filenames |
314 | from the in-memory archive. Returns a list of \f(CW\*(C`Archive::Tar::File\*(C'\fR |
315 | objects that remain. |
316 | .Sh "$tar\->clear" |
317 | .IX Subsection "$tar->clear" |
318 | \&\f(CW\*(C`clear\*(C'\fR clears the current in-memory archive. This effectively gives |
319 | you a 'blank' object, ready to be filled again. Note that \f(CW\*(C`clear\*(C'\fR |
320 | only has effect on the object, not the underlying tarfile. |
321 | .ie n .Sh "$tar\->write ( [$file, $compressed\fP, \f(CW$prefix] )" |
322 | .el .Sh "$tar\->write ( [$file, \f(CW$compressed\fP, \f(CW$prefix\fP] )" |
323 | .IX Subsection "$tar->write ( [$file, $compressed, $prefix] )" |
324 | Write the in-memory archive to disk. The first argument can either |
325 | be the name of a file or a reference to an already open filehandle (a |
326 | \&\s-1GLOB\s0 reference). |
327 | .PP |
328 | The second argument is used to indicate compression. You can either |
329 | compress using \f(CW\*(C`gzip\*(C'\fR or \f(CW\*(C`bzip2\*(C'\fR. If you pass a digit, it's assumed |
330 | to be the \f(CW\*(C`gzip\*(C'\fR compression level (between 1 and 9), but the use of |
331 | constants is prefered: |
332 | .PP |
333 | .Vb 2 |
334 | \& # write a gzip compressed file |
335 | \& $tar\->write( 'out.tgz', COMPRESS_GZIP ); |
336 | .Ve |
337 | .PP |
338 | .Vb 2 |
339 | \& # write a bzip compressed file |
340 | \& $tar\->write( 'out.tbz', COMPRESS_BZIP ); |
341 | .Ve |
342 | .PP |
343 | Note that when you pass in a filehandle, the compression argument |
344 | is ignored, as all files are printed verbatim to your filehandle. |
345 | If you wish to enable compression with filehandles, use an |
346 | \&\f(CW\*(C`IO::Zlib\*(C'\fR or \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR filehandle instead. |
347 | .PP |
348 | The third argument is an optional prefix. All files will be tucked |
349 | away in the directory you specify as prefix. So if you have files |
350 | \&'a' and 'b' in your archive, and you specify 'foo' as prefix, they |
351 | will be written to the archive as 'foo/a' and 'foo/b'. |
352 | .PP |
353 | If no arguments are given, \f(CW\*(C`write\*(C'\fR returns the entire formatted |
354 | archive as a string, which could be useful if you'd like to stuff the |
355 | archive into a socket or a pipe to gzip or something. |
356 | .ie n .Sh "$tar\->add_files( @filenamelist )" |
357 | .el .Sh "$tar\->add_files( \f(CW@filenamelist\fP )" |
358 | .IX Subsection "$tar->add_files( @filenamelist )" |
359 | Takes a list of filenames and adds them to the in-memory archive. |
360 | .PP |
361 | The path to the file is automatically converted to a Unix like |
362 | equivalent for use in the archive, and, if on MacOS, the file's |
363 | modification time is converted from the MacOS epoch to the Unix epoch. |
364 | So tar archives created on MacOS with \fBArchive::Tar\fR can be read |
365 | both with \fItar\fR on Unix and applications like \fIsuntar\fR or |
366 | \&\fIStuffit Expander\fR on MacOS. |
367 | .PP |
368 | Be aware that the file's type/creator and resource fork will be lost, |
369 | which is usually what you want in cross-platform archives. |
370 | .PP |
371 | Instead of a filename, you can also pass it an existing \f(CW\*(C`Archive::Tar::File\*(C'\fR |
372 | object from, for example, another archive. The object will be clone, and |
373 | effectively be a copy of the original, not an alias. |
374 | .PP |
375 | Returns a list of \f(CW\*(C`Archive::Tar::File\*(C'\fR objects that were just added. |
376 | .ie n .Sh "$tar\->add_data ( $filename\fP, \f(CW$data, [$opthashref] )" |
377 | .el .Sh "$tar\->add_data ( \f(CW$filename\fP, \f(CW$data\fP, [$opthashref] )" |
378 | .IX Subsection "$tar->add_data ( $filename, $data, [$opthashref] )" |
379 | Takes a filename, a scalar full of data and optionally a reference to |
380 | a hash with specific options. |
381 | .PP |
382 | Will add a file to the in-memory archive, with name \f(CW$filename\fR and |
383 | content \f(CW$data\fR. Specific properties can be set using \f(CW$opthashref\fR. |
384 | The following list of properties is supported: name, size, mtime |
385 | (last modified date), mode, uid, gid, linkname, uname, gname, |
386 | devmajor, devminor, prefix, type. (On MacOS, the file's path and |
387 | modification times are converted to Unix equivalents.) |
388 | .PP |
389 | Valid values for the file type are the following constants defined in |
390 | Archive::Tar::Constants: |
391 | .IP "\s-1FILE\s0" 4 |
392 | .IX Item "FILE" |
393 | Regular file. |
394 | .IP "\s-1HARDLINK\s0" 4 |
395 | .IX Item "HARDLINK" |
396 | .PD 0 |
397 | .IP "\s-1SYMLINK\s0" 4 |
398 | .IX Item "SYMLINK" |
399 | .PD |
400 | Hard and symbolic (\*(L"soft\*(R") links; linkname should specify target. |
401 | .IP "\s-1CHARDEV\s0" 4 |
402 | .IX Item "CHARDEV" |
403 | .PD 0 |
404 | .IP "\s-1BLOCKDEV\s0" 4 |
405 | .IX Item "BLOCKDEV" |
406 | .PD |
407 | Character and block devices. devmajor and devminor should specify the major |
408 | and minor device numbers. |
409 | .IP "\s-1DIR\s0" 4 |
410 | .IX Item "DIR" |
411 | Directory. |
412 | .IP "\s-1FIFO\s0" 4 |
413 | .IX Item "FIFO" |
414 | \&\s-1FIFO\s0 (named pipe). |
415 | .IP "\s-1SOCKET\s0" 4 |
416 | .IX Item "SOCKET" |
417 | Socket. |
418 | .PP |
419 | Returns the \f(CW\*(C`Archive::Tar::File\*(C'\fR object that was just added, or |
420 | \&\f(CW\*(C`undef\*(C'\fR on failure. |
421 | .Sh "$tar\->error( [$BOOL] )" |
422 | .IX Subsection "$tar->error( [$BOOL] )" |
423 | Returns the current errorstring (usually, the last error reported). |
424 | If a true value was specified, it will give the \f(CW\*(C`Carp::longmess\*(C'\fR |
425 | equivalent of the error, in effect giving you a stacktrace. |
426 | .PP |
427 | For backwards compatibility, this error is also available as |
428 | \&\f(CW$Archive::Tar::error\fR although it is much recommended you use the |
429 | method call instead. |
430 | .ie n .Sh "$tar\->setcwd( $cwd );" |
431 | .el .Sh "$tar\->setcwd( \f(CW$cwd\fP );" |
432 | .IX Subsection "$tar->setcwd( $cwd );" |
433 | \&\f(CW\*(C`Archive::Tar\*(C'\fR needs to know the current directory, and it will run |
434 | \&\f(CW\*(C`Cwd::cwd()\*(C'\fR \fIevery\fR time it extracts a \fIrelative\fR entry from the |
435 | tarfile and saves it in the file system. (As of version 1.30, however, |
436 | \&\f(CW\*(C`Archive::Tar\*(C'\fR will use the speed optimization described below |
437 | automatically, so it's only relevant if you're using \f(CW\*(C`extract_file()\*(C'\fR). |
438 | .PP |
439 | Since \f(CW\*(C`Archive::Tar\*(C'\fR doesn't change the current directory internally |
440 | while it is extracting the items in a tarball, all calls to \f(CW\*(C`Cwd::cwd()\*(C'\fR |
441 | can be avoided if we can guarantee that the current directory doesn't |
442 | get changed externally. |
443 | .PP |
444 | To use this performance boost, set the current directory via |
445 | .PP |
446 | .Vb 2 |
447 | \& use Cwd; |
448 | \& $tar\->setcwd( cwd() ); |
449 | .Ve |
450 | .PP |
451 | once before calling a function like \f(CW\*(C`extract_file\*(C'\fR and |
452 | \&\f(CW\*(C`Archive::Tar\*(C'\fR will use the current directory setting from then on |
453 | and won't call \f(CW\*(C`Cwd::cwd()\*(C'\fR internally. |
454 | .PP |
455 | To switch back to the default behaviour, use |
456 | .PP |
457 | .Vb 1 |
458 | \& $tar\->setcwd( undef ); |
459 | .Ve |
460 | .PP |
461 | and \f(CW\*(C`Archive::Tar\*(C'\fR will call \f(CW\*(C`Cwd::cwd()\*(C'\fR internally again. |
462 | .PP |
463 | If you're using \f(CW\*(C`Archive::Tar\*(C'\fR's \f(CW\*(C`exract()\*(C'\fR method, \f(CW\*(C`setcwd()\*(C'\fR will |
464 | be called for you. |
465 | .SH "Class Methods" |
466 | .IX Header "Class Methods" |
467 | .ie n .Sh "Archive::Tar\->create_archive($file, $compressed\fP, \f(CW@filelist)" |
468 | .el .Sh "Archive::Tar\->create_archive($file, \f(CW$compressed\fP, \f(CW@filelist\fP)" |
469 | .IX Subsection "Archive::Tar->create_archive($file, $compressed, @filelist)" |
470 | Creates a tar file from the list of files provided. The first |
471 | argument can either be the name of the tar file to create or a |
472 | reference to an open file handle (e.g. a \s-1GLOB\s0 reference). |
473 | .PP |
474 | The second argument is used to indicate compression. You can either |
475 | compress using \f(CW\*(C`gzip\*(C'\fR or \f(CW\*(C`bzip2\*(C'\fR. If you pass a digit, it's assumed |
476 | to be the \f(CW\*(C`gzip\*(C'\fR compression level (between 1 and 9), but the use of |
477 | constants is prefered: |
478 | .PP |
479 | .Vb 2 |
480 | \& # write a gzip compressed file |
481 | \& Archive::Tar\->create_archive( 'out.tgz', COMPRESS_GZIP, @filelist ); |
482 | .Ve |
483 | .PP |
484 | .Vb 2 |
485 | \& # write a bzip compressed file |
486 | \& Archive::Tar\->create_archive( 'out.tbz', COMPRESS_BZIP, @filelist ); |
487 | .Ve |
488 | .PP |
489 | Note that when you pass in a filehandle, the compression argument |
490 | is ignored, as all files are printed verbatim to your filehandle. |
491 | If you wish to enable compression with filehandles, use an |
492 | \&\f(CW\*(C`IO::Zlib\*(C'\fR or \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR filehandle instead. |
493 | .PP |
494 | The remaining arguments list the files to be included in the tar file. |
495 | These files must all exist. Any files which don't exist or can't be |
496 | read are silently ignored. |
497 | .PP |
498 | If the archive creation fails for any reason, \f(CW\*(C`create_archive\*(C'\fR will |
499 | return false. Please use the \f(CW\*(C`error\*(C'\fR method to find the cause of the |
500 | failure. |
501 | .PP |
502 | Note that this method does not write \f(CW\*(C`on the fly\*(C'\fR as it were; it |
503 | still reads all the files into memory before writing out the archive. |
504 | Consult the \s-1FAQ\s0 below if this is a problem. |
505 | .ie n .Sh "Archive::Tar\->iter( $filename\fP, [ \f(CW$compressed\fP, {opt => \f(CW$val} ] )" |
506 | .el .Sh "Archive::Tar\->iter( \f(CW$filename\fP, [ \f(CW$compressed\fP, {opt => \f(CW$val\fP} ] )" |
507 | .IX Subsection "Archive::Tar->iter( $filename, [ $compressed, {opt => $val} ] )" |
508 | Returns an iterator function that reads the tar file without loading |
509 | it all in memory. Each time the function is called it will return the |
510 | next file in the tarball. The files are returned as |
511 | \&\f(CW\*(C`Archive::Tar::File\*(C'\fR objects. The iterator function returns the |
512 | empty list once it has exhausted the files contained. |
513 | .PP |
514 | The second argument can be a hash reference with options, which are |
515 | identical to the arguments passed to \f(CW\*(C`read()\*(C'\fR. |
516 | .PP |
517 | Example usage: |
518 | .PP |
519 | .Vb 1 |
520 | \& my $next = Archive::Tar\->iter( "example.tar.gz", 1, {filter => qr/\e.pm$/} ); |
521 | .Ve |
522 | .PP |
523 | .Vb 2 |
524 | \& while( my $f = $next\->() ) { |
525 | \& print $f\->name, "\en"; |
526 | .Ve |
527 | .PP |
528 | .Vb 1 |
529 | \& $f\->extract or warn "Extraction failed"; |
530 | .Ve |
531 | .PP |
532 | .Vb 2 |
533 | \& # .... |
534 | \& } |
535 | .Ve |
536 | .ie n .Sh "Archive::Tar\->list_archive($file, $compressed, [\e@properties])" |
537 | .el .Sh "Archive::Tar\->list_archive($file, \f(CW$compressed\fP, [\e@properties])" |
538 | .IX Subsection "Archive::Tar->list_archive($file, $compressed, [@properties])" |
539 | Returns a list of the names of all the files in the archive. The |
540 | first argument can either be the name of the tar file to list or a |
541 | reference to an open file handle (e.g. a \s-1GLOB\s0 reference). |
542 | .PP |
543 | If \f(CW\*(C`list_archive()\*(C'\fR is passed an array reference as its third |
544 | argument it returns a list of hash references containing the requested |
545 | properties of each file. The following list of properties is |
546 | supported: full_path, name, size, mtime (last modified date), mode, |
547 | uid, gid, linkname, uname, gname, devmajor, devminor, prefix. |
548 | .PP |
549 | See \f(CW\*(C`Archive::Tar::File\*(C'\fR for details about supported properties. |
550 | .PP |
551 | Passing an array reference containing only one element, 'name', is |
552 | special cased to return a list of names rather than a list of hash |
553 | references. |
554 | .ie n .Sh "Archive::Tar\->extract_archive($file, $compressed)" |
555 | .el .Sh "Archive::Tar\->extract_archive($file, \f(CW$compressed\fP)" |
556 | .IX Subsection "Archive::Tar->extract_archive($file, $compressed)" |
557 | Extracts the contents of the tar file. The first argument can either |
558 | be the name of the tar file to create or a reference to an open file |
559 | handle (e.g. a \s-1GLOB\s0 reference). All relative paths in the tar file will |
560 | be created underneath the current working directory. |
561 | .PP |
562 | \&\f(CW\*(C`extract_archive\*(C'\fR will return a list of files it extracted. |
563 | If the archive extraction fails for any reason, \f(CW\*(C`extract_archive\*(C'\fR |
564 | will return false. Please use the \f(CW\*(C`error\*(C'\fR method to find the cause |
565 | of the failure. |
566 | .Sh "$bool = Archive::Tar\->has_io_string" |
567 | .IX Subsection "$bool = Archive::Tar->has_io_string" |
568 | Returns true if we currently have \f(CW\*(C`IO::String\*(C'\fR support loaded. |
569 | .PP |
570 | Either \f(CW\*(C`IO::String\*(C'\fR or \f(CW\*(C`perlio\*(C'\fR support is needed to support writing |
571 | stringified archives. Currently, \f(CW\*(C`perlio\*(C'\fR is the preferred method, if |
572 | available. |
573 | .PP |
574 | See the \f(CW\*(C`GLOBAL VARIABLES\*(C'\fR section to see how to change this preference. |
575 | .Sh "$bool = Archive::Tar\->has_perlio" |
576 | .IX Subsection "$bool = Archive::Tar->has_perlio" |
577 | Returns true if we currently have \f(CW\*(C`perlio\*(C'\fR support loaded. |
578 | .PP |
579 | This requires \f(CW\*(C`perl\-5.8\*(C'\fR or higher, compiled with \f(CW\*(C`perlio\*(C'\fR |
580 | .PP |
581 | Either \f(CW\*(C`IO::String\*(C'\fR or \f(CW\*(C`perlio\*(C'\fR support is needed to support writing |
582 | stringified archives. Currently, \f(CW\*(C`perlio\*(C'\fR is the preferred method, if |
583 | available. |
584 | .PP |
585 | See the \f(CW\*(C`GLOBAL VARIABLES\*(C'\fR section to see how to change this preference. |
586 | .Sh "$bool = Archive::Tar\->has_zlib_support" |
587 | .IX Subsection "$bool = Archive::Tar->has_zlib_support" |
588 | Returns true if \f(CW\*(C`Archive::Tar\*(C'\fR can extract \f(CW\*(C`zlib\*(C'\fR compressed archives |
589 | .Sh "$bool = Archive::Tar\->has_bzip2_support" |
590 | .IX Subsection "$bool = Archive::Tar->has_bzip2_support" |
591 | Returns true if \f(CW\*(C`Archive::Tar\*(C'\fR can extract \f(CW\*(C`bzip2\*(C'\fR compressed archives |
592 | .Sh "Archive::Tar\->can_handle_compressed_files" |
593 | .IX Subsection "Archive::Tar->can_handle_compressed_files" |
594 | A simple checking routine, which will return true if \f(CW\*(C`Archive::Tar\*(C'\fR |
595 | is able to uncompress compressed archives on the fly with \f(CW\*(C`IO::Zlib\*(C'\fR |
596 | and \f(CW\*(C`IO::Compress::Bzip2\*(C'\fR or false if not both are installed. |
597 | .PP |
598 | You can use this as a shortcut to determine whether \f(CW\*(C`Archive::Tar\*(C'\fR |
599 | will do what you think before passing compressed archives to its |
600 | \&\f(CW\*(C`read\*(C'\fR method. |
601 | .SH "GLOBAL VARIABLES" |
602 | .IX Header "GLOBAL VARIABLES" |
603 | .Sh "$Archive::Tar::FOLLOW_SYMLINK" |
604 | .IX Subsection "$Archive::Tar::FOLLOW_SYMLINK" |
605 | Set this variable to \f(CW1\fR to make \f(CW\*(C`Archive::Tar\*(C'\fR effectively make a |
606 | copy of the file when extracting. Default is \f(CW0\fR, which |
607 | means the symlink stays intact. Of course, you will have to pack the |
608 | file linked to as well. |
609 | .PP |
610 | This option is checked when you write out the tarfile using \f(CW\*(C`write\*(C'\fR |
611 | or \f(CW\*(C`create_archive\*(C'\fR. |
612 | .PP |
613 | This works just like \f(CW\*(C`/bin/tar\*(C'\fR's \f(CW\*(C`\-h\*(C'\fR option. |
614 | .Sh "$Archive::Tar::CHOWN" |
615 | .IX Subsection "$Archive::Tar::CHOWN" |
616 | By default, \f(CW\*(C`Archive::Tar\*(C'\fR will try to \f(CW\*(C`chown\*(C'\fR your files if it is |
617 | able to. In some cases, this may not be desired. In that case, set |
618 | this variable to \f(CW0\fR to disable \f(CW\*(C`chown\*(C'\fR\-ing, even if it were |
619 | possible. |
620 | .PP |
621 | The default is \f(CW1\fR. |
622 | .Sh "$Archive::Tar::CHMOD" |
623 | .IX Subsection "$Archive::Tar::CHMOD" |
624 | By default, \f(CW\*(C`Archive::Tar\*(C'\fR will try to \f(CW\*(C`chmod\*(C'\fR your files to |
625 | whatever mode was specified for the particular file in the archive. |
626 | In some cases, this may not be desired. In that case, set this |
627 | variable to \f(CW0\fR to disable \f(CW\*(C`chmod\*(C'\fR\-ing. |
628 | .PP |
629 | The default is \f(CW1\fR. |
630 | .Sh "$Archive::Tar::SAME_PERMISSIONS" |
631 | .IX Subsection "$Archive::Tar::SAME_PERMISSIONS" |
632 | When, \f(CW$Archive::Tar::CHMOD\fR is enabled, this setting controls whether |
633 | the permissions on files from the archive are used without modification |
634 | of if they are filtered by removing any setid bits and applying the |
635 | current umask. |
636 | .PP |
637 | The default is \f(CW1\fR for the root user and \f(CW0\fR for normal users. |
638 | .Sh "$Archive::Tar::DO_NOT_USE_PREFIX" |
639 | .IX Subsection "$Archive::Tar::DO_NOT_USE_PREFIX" |
640 | By default, \f(CW\*(C`Archive::Tar\*(C'\fR will try to put paths that are over |
641 | 100 characters in the \f(CW\*(C`prefix\*(C'\fR field of your tar header, as |
642 | defined per POSIX\-standard. However, some (older) tar programs |
643 | do not implement this spec. To retain compatibility with these older |
644 | or non-POSIX compliant versions, you can set the \f(CW$DO_NOT_USE_PREFIX\fR |
645 | variable to a true value, and \f(CW\*(C`Archive::Tar\*(C'\fR will use an alternate |
646 | way of dealing with paths over 100 characters by using the |
647 | \&\f(CW\*(C`GNU Extended Header\*(C'\fR feature. |
648 | .PP |
649 | Note that clients who do not support the \f(CW\*(C`GNU Extended Header\*(C'\fR |
650 | feature will not be able to read these archives. Such clients include |
651 | tars on \f(CW\*(C`Solaris\*(C'\fR, \f(CW\*(C`Irix\*(C'\fR and \f(CW\*(C`AIX\*(C'\fR. |
652 | .PP |
653 | The default is \f(CW0\fR. |
654 | .Sh "$Archive::Tar::DEBUG" |
655 | .IX Subsection "$Archive::Tar::DEBUG" |
656 | Set this variable to \f(CW1\fR to always get the \f(CW\*(C`Carp::longmess\*(C'\fR output |
657 | of the warnings, instead of the regular \f(CW\*(C`carp\*(C'\fR. This is the same |
658 | message you would get by doing: |
659 | .PP |
660 | .Vb 1 |
661 | \& $tar\->error(1); |
662 | .Ve |
663 | .PP |
664 | Defaults to \f(CW0\fR. |
665 | .Sh "$Archive::Tar::WARN" |
666 | .IX Subsection "$Archive::Tar::WARN" |
667 | Set this variable to \f(CW0\fR if you do not want any warnings printed. |
668 | Personally I recommend against doing this, but people asked for the |
669 | option. Also, be advised that this is of course not threadsafe. |
670 | .PP |
671 | Defaults to \f(CW1\fR. |
672 | .Sh "$Archive::Tar::error" |
673 | .IX Subsection "$Archive::Tar::error" |
674 | Holds the last reported error. Kept for historical reasons, but its |
675 | use is very much discouraged. Use the \f(CW\*(C`error()\*(C'\fR method instead: |
676 | .PP |
677 | .Vb 1 |
678 | \& warn $tar\->error unless $tar\->extract; |
679 | .Ve |
680 | .PP |
681 | Note that in older versions of this module, the \f(CW\*(C`error()\*(C'\fR method |
682 | would return an effectively global value even when called an instance |
683 | method as above. This has since been fixed, and multiple instances of |
684 | \&\f(CW\*(C`Archive::Tar\*(C'\fR now have separate error strings. |
685 | .Sh "$Archive::Tar::INSECURE_EXTRACT_MODE" |
686 | .IX Subsection "$Archive::Tar::INSECURE_EXTRACT_MODE" |
687 | This variable indicates whether \f(CW\*(C`Archive::Tar\*(C'\fR should allow |
688 | files to be extracted outside their current working directory. |
689 | .PP |
690 | Allowing this could have security implications, as a malicious |
691 | tar archive could alter or replace any file the extracting user |
692 | has permissions to. Therefor, the default is to not allow |
693 | insecure extractions. |
694 | .PP |
695 | If you trust the archive, or have other reasons to allow the |
696 | archive to write files outside your current working directory, |
697 | set this variable to \f(CW\*(C`true\*(C'\fR. |
698 | .PP |
699 | Note that this is a backwards incompatible change from version |
700 | \&\f(CW1.36\fR and before. |
701 | .Sh "$Archive::Tar::HAS_PERLIO" |
702 | .IX Subsection "$Archive::Tar::HAS_PERLIO" |
703 | This variable holds a boolean indicating if we currently have |
704 | \&\f(CW\*(C`perlio\*(C'\fR support loaded. This will be enabled for any perl |
705 | greater than \f(CW5.8\fR compiled with \f(CW\*(C`perlio\*(C'\fR. |
706 | .PP |
707 | If you feel strongly about disabling it, set this variable to |
708 | \&\f(CW\*(C`false\*(C'\fR. Note that you will then need \f(CW\*(C`IO::String\*(C'\fR installed |
709 | to support writing stringified archives. |
710 | .PP |
711 | Don't change this variable unless you \fBreally\fR know what you're |
712 | doing. |
713 | .Sh "$Archive::Tar::HAS_IO_STRING" |
714 | .IX Subsection "$Archive::Tar::HAS_IO_STRING" |
715 | This variable holds a boolean indicating if we currently have |
716 | \&\f(CW\*(C`IO::String\*(C'\fR support loaded. This will be enabled for any perl |
717 | that has a loadable \f(CW\*(C`IO::String\*(C'\fR module. |
718 | .PP |
719 | If you feel strongly about disabling it, set this variable to |
720 | \&\f(CW\*(C`false\*(C'\fR. Note that you will then need \f(CW\*(C`perlio\*(C'\fR support from |
721 | your perl to be able to write stringified archives. |
722 | .PP |
723 | Don't change this variable unless you \fBreally\fR know what you're |
724 | doing. |
725 | .SH "FAQ" |
726 | .IX Header "FAQ" |
727 | .IP "What's the minimum perl version required to run Archive::Tar?" 4 |
728 | .IX Item "What's the minimum perl version required to run Archive::Tar?" |
729 | You will need perl version 5.005_03 or newer. |
730 | .IP "Isn't Archive::Tar slow?" 4 |
731 | .IX Item "Isn't Archive::Tar slow?" |
732 | Yes it is. It's pure perl, so it's a lot slower then your \f(CW\*(C`/bin/tar\*(C'\fR |
733 | However, it's very portable. If speed is an issue, consider using |
734 | \&\f(CW\*(C`/bin/tar\*(C'\fR instead. |
735 | .IP "Isn't Archive::Tar heavier on memory than /bin/tar?" 4 |
736 | .IX Item "Isn't Archive::Tar heavier on memory than /bin/tar?" |
737 | Yes it is, see previous answer. Since \f(CW\*(C`Compress::Zlib\*(C'\fR and therefore |
738 | \&\f(CW\*(C`IO::Zlib\*(C'\fR doesn't support \f(CW\*(C`seek\*(C'\fR on their filehandles, there is little |
739 | choice but to read the archive into memory. |
740 | This is ok if you want to do in-memory manipulation of the archive. |
741 | .Sp |
742 | If you just want to extract, use the \f(CW\*(C`extract_archive\*(C'\fR class method |
743 | instead. It will optimize and write to disk immediately. |
744 | .Sp |
745 | Another option is to use the \f(CW\*(C`iter\*(C'\fR class method to iterate over |
746 | the files in the tarball without reading them all in memory at once. |
747 | .IP "Can you lazy-load data instead?" 4 |
748 | .IX Item "Can you lazy-load data instead?" |
749 | In some cases, yes. You can use the \f(CW\*(C`iter\*(C'\fR class method to iterate |
750 | over the files in the tarball without reading them all in memory at once. |
751 | .IP "How much memory will an X kb tar file need?" 4 |
752 | .IX Item "How much memory will an X kb tar file need?" |
753 | Probably more than X kb, since it will all be read into memory. If |
754 | this is a problem, and you don't need to do in memory manipulation |
755 | of the archive, consider using the \f(CW\*(C`iter\*(C'\fR class method, or \f(CW\*(C`/bin/tar\*(C'\fR |
756 | instead. |
757 | .IP "What do you do with unsupported filetypes in an archive?" 4 |
758 | .IX Item "What do you do with unsupported filetypes in an archive?" |
759 | \&\f(CW\*(C`Unix\*(C'\fR has a few filetypes that aren't supported on other platforms, |
760 | like \f(CW\*(C`Win32\*(C'\fR. If we encounter a \f(CW\*(C`hardlink\*(C'\fR or \f(CW\*(C`symlink\*(C'\fR we'll just |
761 | try to make a copy of the original file, rather than throwing an error. |
762 | .Sp |
763 | This does require you to read the entire archive in to memory first, |
764 | since otherwise we wouldn't know what data to fill the copy with. |
765 | (This means that you cannot use the class methods, including \f(CW\*(C`iter\*(C'\fR |
766 | on archives that have incompatible filetypes and still expect things |
767 | to work). |
768 | .Sp |
769 | For other filetypes, like \f(CW\*(C`chardevs\*(C'\fR and \f(CW\*(C`blockdevs\*(C'\fR we'll warn that |
770 | the extraction of this particular item didn't work. |
771 | .IP "I'm using WinZip, or some other non-POSIX client, and files are not being extracted properly!" 4 |
772 | .IX Item "I'm using WinZip, or some other non-POSIX client, and files are not being extracted properly!" |
773 | By default, \f(CW\*(C`Archive::Tar\*(C'\fR is in a completely POSIX-compatible |
774 | mode, which uses the POSIX-specification of \f(CW\*(C`tar\*(C'\fR to store files. |
775 | For paths greather than 100 characters, this is done using the |
776 | \&\f(CW\*(C`POSIX header prefix\*(C'\fR. Non-POSIX-compatible clients may not support |
777 | this part of the specification, and may only support the \f(CW\*(C`GNU Extended |
778 | Header\*(C'\fR functionality. To facilitate those clients, you can set the |
779 | \&\f(CW$Archive::Tar::DO_NOT_USE_PREFIX\fR variable to \f(CW\*(C`true\*(C'\fR. See the |
780 | \&\f(CW\*(C`GLOBAL VARIABLES\*(C'\fR section for details on this variable. |
781 | .Sp |
782 | Note that \s-1GNU\s0 tar earlier than version 1.14 does not cope well with |
783 | the \f(CW\*(C`POSIX header prefix\*(C'\fR. If you use such a version, consider setting |
784 | the \f(CW$Archive::Tar::DO_NOT_USE_PREFIX\fR variable to \f(CW\*(C`true\*(C'\fR. |
785 | .IP "How do I extract only files that have property X from an archive?" 4 |
786 | .IX Item "How do I extract only files that have property X from an archive?" |
787 | Sometimes, you might not wish to extract a complete archive, just |
788 | the files that are relevant to you, based on some criteria. |
789 | .Sp |
790 | You can do this by filtering a list of \f(CW\*(C`Archive::Tar::File\*(C'\fR objects |
791 | based on your criteria. For example, to extract only files that have |
792 | the string \f(CW\*(C`foo\*(C'\fR in their title, you would use: |
793 | .Sp |
794 | .Vb 3 |
795 | \& $tar\->extract( |
796 | \& grep { $_\->full_path =~ /foo/ } $tar\->get_files |
797 | \& ); |
798 | .Ve |
799 | .Sp |
800 | This way, you can filter on any attribute of the files in the archive. |
801 | Consult the \f(CW\*(C`Archive::Tar::File\*(C'\fR documentation on how to use these |
802 | objects. |
803 | .IP "How do I access .tar.Z files?" 4 |
804 | .IX Item "How do I access .tar.Z files?" |
805 | The \f(CW\*(C`Archive::Tar\*(C'\fR module can optionally use \f(CW\*(C`Compress::Zlib\*(C'\fR (via |
806 | the \f(CW\*(C`IO::Zlib\*(C'\fR module) to access tar files that have been compressed |
807 | with \f(CW\*(C`gzip\*(C'\fR. Unfortunately tar files compressed with the Unix \f(CW\*(C`compress\*(C'\fR |
808 | utility cannot be read by \f(CW\*(C`Compress::Zlib\*(C'\fR and so cannot be directly |
809 | accesses by \f(CW\*(C`Archive::Tar\*(C'\fR. |
810 | .Sp |
811 | If the \f(CW\*(C`uncompress\*(C'\fR or \f(CW\*(C`gunzip\*(C'\fR programs are available, you can use |
812 | one of these workarounds to read \f(CW\*(C`.tar.Z\*(C'\fR files from \f(CW\*(C`Archive::Tar\*(C'\fR |
813 | .Sp |
814 | Firstly with \f(CW\*(C`uncompress\*(C'\fR |
815 | .Sp |
816 | .Vb 1 |
817 | \& use Archive::Tar; |
818 | .Ve |
819 | .Sp |
820 | .Vb 3 |
821 | \& open F, "uncompress \-c $filename |"; |
822 | \& my $tar = Archive::Tar\->new(*F); |
823 | \& ... |
824 | .Ve |
825 | .Sp |
826 | and this with \f(CW\*(C`gunzip\*(C'\fR |
827 | .Sp |
828 | .Vb 1 |
829 | \& use Archive::Tar; |
830 | .Ve |
831 | .Sp |
832 | .Vb 3 |
833 | \& open F, "gunzip \-c $filename |"; |
834 | \& my $tar = Archive::Tar\->new(*F); |
835 | \& ... |
836 | .Ve |
837 | .Sp |
838 | Similarly, if the \f(CW\*(C`compress\*(C'\fR program is available, you can use this to |
839 | write a \f(CW\*(C`.tar.Z\*(C'\fR file |
840 | .Sp |
841 | .Vb 2 |
842 | \& use Archive::Tar; |
843 | \& use IO::File; |
844 | .Ve |
845 | .Sp |
846 | .Vb 5 |
847 | \& my $fh = new IO::File "| compress \-c >$filename"; |
848 | \& my $tar = Archive::Tar\->new(); |
849 | \& ... |
850 | \& $tar\->write($fh); |
851 | \& $fh\->close ; |
852 | .Ve |
853 | .IP "How do I handle Unicode strings?" 4 |
854 | .IX Item "How do I handle Unicode strings?" |
855 | \&\f(CW\*(C`Archive::Tar\*(C'\fR uses byte semantics for any files it reads from or writes |
856 | to disk. This is not a problem if you only deal with files and never |
857 | look at their content or work solely with byte strings. But if you use |
858 | Unicode strings with character semantics, some additional steps need |
859 | to be taken. |
860 | .Sp |
861 | For example, if you add a Unicode string like |
862 | .Sp |
863 | .Vb 2 |
864 | \& # Problem |
865 | \& $tar\->add_data('file.txt', "Euro: \ex{20AC}"); |
866 | .Ve |
867 | .Sp |
868 | then there will be a problem later when the tarfile gets written out |
869 | to disk via \f(CW\*(C`$tar\-\*(C'\fR\fIwrite()\fR>: |
870 | .Sp |
871 | .Vb 1 |
872 | \& Wide character in print at .../Archive/Tar.pm line 1014. |
873 | .Ve |
874 | .Sp |
875 | The data was added as a Unicode string and when writing it out to disk, |
876 | the \f(CW\*(C`:utf8\*(C'\fR line discipline wasn't set by \f(CW\*(C`Archive::Tar\*(C'\fR, so Perl |
877 | tried to convert the string to \s-1ISO\-8859\s0 and failed. The written file |
878 | now contains garbage. |
879 | .Sp |
880 | For this reason, Unicode strings need to be converted to UTF\-8\-encoded |
881 | bytestrings before they are handed off to \f(CW\*(C`add_data()\*(C'\fR: |
882 | .Sp |
883 | .Vb 3 |
884 | \& use Encode; |
885 | \& my $data = "Accented character: \ex{20AC}"; |
886 | \& $data = encode('utf8', $data); |
887 | .Ve |
888 | .Sp |
889 | .Vb 1 |
890 | \& $tar\->add_data('file.txt', $data); |
891 | .Ve |
892 | .Sp |
893 | A opposite problem occurs if you extract a UTF8\-encoded file from a |
894 | tarball. Using \f(CW\*(C`get_content()\*(C'\fR on the \f(CW\*(C`Archive::Tar::File\*(C'\fR object |
895 | will return its content as a bytestring, not as a Unicode string. |
896 | .Sp |
897 | If you want it to be a Unicode string (because you want character |
898 | semantics with operations like regular expression matching), you need |
899 | to decode the UTF8\-encoded content and have Perl convert it into |
900 | a Unicode string: |
901 | .Sp |
902 | .Vb 2 |
903 | \& use Encode; |
904 | \& my $data = $tar\->get_content(); |
905 | .Ve |
906 | .Sp |
907 | .Vb 2 |
908 | \& # Make it a Unicode string |
909 | \& $data = decode('utf8', $data); |
910 | .Ve |
911 | .Sp |
912 | There is no easy way to provide this functionality in \f(CW\*(C`Archive::Tar\*(C'\fR, |
913 | because a tarball can contain many files, and each of which could be |
914 | encoded in a different way. |
915 | .SH "CAVEATS" |
916 | .IX Header "CAVEATS" |
917 | The \s-1AIX\s0 tar does not fill all unused space in the tar archive with 0x00. |
918 | This sometimes leads to warning messages from \f(CW\*(C`Archive::Tar\*(C'\fR. |
919 | .PP |
920 | .Vb 1 |
921 | \& Invalid header block at offset nnn |
922 | .Ve |
923 | .PP |
924 | A fix for that problem is scheduled to be released in the following levels |
925 | of \s-1AIX\s0, all of which should be coming out in the 4th quarter of 2009: |
926 | .PP |
927 | .Vb 4 |
928 | \& AIX 5.3 TL7 SP10 |
929 | \& AIX 5.3 TL8 SP8 |
930 | \& AIX 5.3 TL9 SP5 |
931 | \& AIX 5.3 TL10 SP2 |
932 | .Ve |
933 | .PP |
934 | .Vb 4 |
935 | \& AIX 6.1 TL0 SP11 |
936 | \& AIX 6.1 TL1 SP7 |
937 | \& AIX 6.1 TL2 SP6 |
938 | \& AIX 6.1 TL3 SP3 |
939 | .Ve |
940 | .PP |
941 | The \s-1IBM\s0 \s-1APAR\s0 number for this problem is \s-1IZ50240\s0 (Reported component \s-1ID:\s0 |
942 | 5765G0300 / \s-1AIX\s0 5.3). It is possible to get an ifix for that problem. |
943 | If you need an ifix please contact your local \s-1IBM\s0 \s-1AIX\s0 support. |
944 | .SH "TODO" |
945 | .IX Header "TODO" |
946 | .IP "Check if passed in handles are open for read/write" 4 |
947 | .IX Item "Check if passed in handles are open for read/write" |
948 | Currently I don't know of any portable pure perl way to do this. |
949 | Suggestions welcome. |
950 | .IP "Allow archives to be passed in as string" 4 |
951 | .IX Item "Allow archives to be passed in as string" |
952 | Currently, we only allow opened filehandles or filenames, but |
953 | not strings. The internals would need some reworking to facilitate |
954 | stringified archives. |
955 | .IP "Facilitate processing an opened filehandle of a compressed archive" 4 |
956 | .IX Item "Facilitate processing an opened filehandle of a compressed archive" |
957 | Currently, we only support this if the filehandle is an IO::Zlib object. |
958 | Environments, like apache, will present you with an opened filehandle |
959 | to an uploaded file, which might be a compressed archive. |
960 | .SH "SEE ALSO" |
961 | .IX Header "SEE ALSO" |
962 | .IP "The \s-1GNU\s0 tar specification" 4 |
963 | .IX Item "The GNU tar specification" |
964 | \&\f(CW\*(C`http://www.gnu.org/software/tar/manual/tar.html\*(C'\fR |
965 | .IP "The \s-1PAX\s0 format specication" 4 |
966 | .IX Item "The PAX format specication" |
967 | The specifcation which tar derives from; \f(CW\*(C` http://www.opengroup.org/onlinepubs/007904975/utilities/pax.html\*(C'\fR |
968 | .ie n .IP "A comparison of \s-1GNU\s0 and \s-1POSIX\s0 tar standards; ""http://www.delorie.com/gnu/docs/tar/tar_114.html""" 4 |
969 | .el .IP "A comparison of \s-1GNU\s0 and \s-1POSIX\s0 tar standards; \f(CWhttp://www.delorie.com/gnu/docs/tar/tar_114.html\fR" 4 |
970 | .IX Item "A comparison of GNU and POSIX tar standards; http://www.delorie.com/gnu/docs/tar/tar_114.html" |
971 | .PD 0 |
972 | .IP "\s-1GNU\s0 tar intends to switch to \s-1POSIX\s0 compatibility" 4 |
973 | .IX Item "GNU tar intends to switch to POSIX compatibility" |
974 | .PD |
975 | \&\s-1GNU\s0 Tar authors have expressed their intention to become completely |
976 | POSIX\-compatible; \f(CW\*(C`http://www.gnu.org/software/tar/manual/html_node/Formats.html\*(C'\fR |
977 | .IP "A Comparison between various tar implementations" 4 |
978 | .IX Item "A Comparison between various tar implementations" |
979 | Lists known issues and incompatibilities; \f(CW\*(C`http://gd.tuwien.ac.at/utils/archivers/star/README.otherbugs\*(C'\fR |
980 | .SH "AUTHOR" |
981 | .IX Header "AUTHOR" |
982 | This module by Jos Boumans <kane@cpan.org>. |
983 | .PP |
984 | Please reports bugs to <bug\-archive\-tar@rt.cpan.org>. |
985 | .SH "ACKNOWLEDGEMENTS" |
986 | .IX Header "ACKNOWLEDGEMENTS" |
987 | Thanks to Sean Burke, Chris Nandor, Chip Salzenberg, Tim Heaney, Gisle Aas, |
988 | Rainer Tammer and especially Andrew Savige for their help and suggestions. |
989 | .SH "COPYRIGHT" |
990 | .IX Header "COPYRIGHT" |
991 | This module is copyright (c) 2002 \- 2009 Jos Boumans |
992 | <kane@cpan.org>. All rights reserved. |
993 | .PP |
994 | This library is free software; you may redistribute and/or modify |
995 | it under the same terms as Perl itself. |