Debian Codegraph @

upstream/debian-unstable/man3/Archive::Tar.3perl

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