Debian Codegraph @

upstream/mageia-cauldron/man3pm/Archive::Tar.3pm

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