{
    "mode": "perldoc",
    "parameter": "Archive::Tar",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Archive%3A%3ATar/json",
    "generated": "2026-06-10T07:03:22Z",
    "synopsis": "use Archive::Tar;\nmy $tar = Archive::Tar->new;\n$tar->read('origin.tgz');\n$tar->extract();\n$tar->addfiles('file/foo.pl', 'docs/README');\n$tar->adddata('file/baz.txt', 'This is the contents now');\n$tar->rename('oldname', 'new/file/name');\n$tar->chown('/', 'root');\n$tar->chown('/', 'root:root');\n$tar->chmod('/tmp', '1777');\n$tar->write('files.tar');                   # plain tar\n$tar->write('files.tgz', COMPRESSGZIP);    # gzip compressed\n$tar->write('files.tbz', COMPRESSBZIP);    # bzip2 compressed\n$tar->write('files.txz', COMPRESSXZ);      # xz compressed",
    "sections": {
        "NAME": {
            "content": "Archive::Tar - module for manipulations of tar archives\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use Archive::Tar;\nmy $tar = Archive::Tar->new;\n\n$tar->read('origin.tgz');\n$tar->extract();\n\n$tar->addfiles('file/foo.pl', 'docs/README');\n$tar->adddata('file/baz.txt', 'This is the contents now');\n\n$tar->rename('oldname', 'new/file/name');\n$tar->chown('/', 'root');\n$tar->chown('/', 'root:root');\n$tar->chmod('/tmp', '1777');\n\n$tar->write('files.tar');                   # plain tar\n$tar->write('files.tgz', COMPRESSGZIP);    # gzip compressed\n$tar->write('files.tbz', COMPRESSBZIP);    # bzip2 compressed\n$tar->write('files.txz', COMPRESSXZ);      # xz compressed\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Archive::Tar provides an object oriented mechanism for handling tar files. It provides class\nmethods for quick and easy files handling while also allowing for the creation of tar file\nobjects for custom manipulation. If you have the IO::Zlib module installed, Archive::Tar will\nalso support compressed or gzipped tar files.\n\nAn object of class Archive::Tar represents a .tar(.gz) archive full of files and things.\n",
            "subsections": []
        },
        "Object Methods": {
            "content": "Archive::Tar->new( [$file, $compressed] )\nReturns a new Tar object. If given any arguments, \"new()\" calls the \"read()\" method\nautomatically, passing on the arguments provided to the \"read()\" method.\n\nIf \"new()\" is invoked with arguments and the \"read()\" method fails for any reason, \"new()\"\nreturns undef.\n\n$tar->read ( $filename|$handle, [$compressed, {opt => 'val'}] )\nRead the given tar file into memory. The first argument can either be the name of a file or a\nreference to an already open filehandle (or an IO::Zlib object if it's compressed)\n\nThe \"read\" will *replace* any previous content in $tar!\n\nThe second argument may be considered optional, but remains for backwards compatibility.\nArchive::Tar now looks at the file magic to determine what class should be used to open the file\nand will transparently Do The Right Thing.\n\nArchive::Tar will warn if you try to pass a bzip2 / xz compressed file and the\nIO::Uncompress::Bunzip2 / IO::Uncompress::UnXz are not available and simply return.\n\nNote that you can currently not pass a \"gzip\" compressed filehandle, which is not opened with\n\"IO::Zlib\", a \"bzip2\" compressed filehandle, which is not opened with \"IO::Uncompress::Bunzip2\",\na \"xz\" compressed filehandle, which is not opened with \"IO::Uncompress::UnXz\", nor a string\ncontaining the full archive information (either compressed or uncompressed). These are worth\nwhile features, but not currently implemented. See the \"TODO\" section.\n\nThe third argument can be a hash reference with options. Note that all options are\ncase-sensitive.\n\nlimit\nDo not read more than \"limit\" files. This is useful if you have very big archives, and are\nonly interested in the first few files.\n\nfilter\nCan be set to a regular expression. Only files with names that match the expression will be\nread.\n\nmd5 Set to 1 and the md5sum of files will be returned (instead of file data) my $iter =\nArchive::Tar->iter( $file, 1, {md5 => 1} ); while( my $f = $iter->() ) { print $f->data .\n\"\\t\" . $f->fullpath . $/; }\n\nextract\nIf set to true, immediately extract entries when reading them. This gives you the same\nmemory break as the \"extractarchive\" function. Note however that entries will not be read\ninto memory, but written straight to disk. This means no \"Archive::Tar::File\" objects are\ncreated for you to inspect.\n\nAll files are stored internally as \"Archive::Tar::File\" objects. Please consult the\nArchive::Tar::File documentation for details.\n\nReturns the number of files read in scalar context, and a list of \"Archive::Tar::File\" objects\nin list context.\n\n$tar->containsfile( $filename )\nCheck if the archive contains a certain file. It will return true if the file is in the archive,\nfalse otherwise.\n\nNote however, that this function does an exact match using \"eq\" on the full path. So it cannot\ncompensate for case-insensitive file- systems or compare 2 paths to see if they would point to\nthe same underlying file.\n\n$tar->extract( [@filenames] )\nWrite files whose names are equivalent to any of the names in @filenames to disk, creating\nsubdirectories as necessary. This might not work too well under VMS. Under MacPerl, the file's\nmodification time will be converted to the MacOS zero of time, and appropriate conversions will\nbe done to the path. However, the length of each element of the path is not inspected to see\nwhether it's longer than MacOS currently allows (32 characters).\n\nIf \"extract\" is called without a list of file names, the entire contents of the archive are\nextracted.\n\nReturns a list of filenames extracted.\n\n$tar->extractfile( $file, [$extractpath] )\nWrite an entry, whose name is equivalent to the file name provided to disk. Optionally takes a\nsecond parameter, which is the full native path (including filename) the entry will be written\nto.\n\nFor example:\n\n$tar->extractfile( 'name/in/archive', 'name/i/want/to/give/it' );\n\n$tar->extractfile( $atfileobject,   'name/i/want/to/give/it' );\n\nReturns true on success, false on failure.\n\n$tar->listfiles( [\\@properties] )\nReturns a list of the names of all the files in the archive.\n\nIf \"listfiles()\" is passed an array reference as its first argument it returns a list of hash\nreferences containing the requested properties of each file. The following list of properties is\nsupported: name, size, mtime (last modified date), mode, uid, gid, linkname, uname, gname,\ndevmajor, devminor, prefix.\n\nPassing an array reference containing only one element, 'name', is special cased to return a\nlist of names rather than a list of hash references, making it equivalent to calling\n\"listfiles\" without arguments.\n\n$tar->getfiles( [@filenames] )\nReturns the \"Archive::Tar::File\" objects matching the filenames provided. If no filename list\nwas passed, all \"Archive::Tar::File\" objects in the current Tar object are returned.\n\nPlease refer to the \"Archive::Tar::File\" documentation on how to handle these objects.\n\n$tar->getcontent( $file )\nReturn the content of the named file.\n\n$tar->replacecontent( $file, $content )\nMake the string $content be the content for the file named $file.\n\n$tar->rename( $file, $newname )\nRename the file of the in-memory archive to $newname.\n\nNote that you must specify a Unix path for $newname, since per tar standard, all files in the\narchive must be Unix paths.\n\nReturns true on success and false on failure.\n\n$tar->chmod( $file, $mode )\nChange mode of $file to $mode.\n\nReturns true on success and false on failure.\n\n$tar->chown( $file, $uname [, $gname] )\nChange owner $file to $uname and $gname.\n\nReturns true on success and false on failure.\n\n$tar->remove (@filenamelist)\nRemoves any entries with names matching any of the given filenames from the in-memory archive.\nReturns a list of \"Archive::Tar::File\" objects that remain.\n\n$tar->clear\n\"clear\" clears the current in-memory archive. This effectively gives you a 'blank' object, ready\nto be filled again. Note that \"clear\" only has effect on the object, not the underlying tarfile.\n\n$tar->write ( [$file, $compressed, $prefix] )\nWrite the in-memory archive to disk. The first argument can either be the name of a file or a\nreference to an already open filehandle (a GLOB reference).\n\nThe second argument is used to indicate compression. You can compress using \"gzip\", \"bzip2\" or\n\"xz\". If you pass a digit, it's assumed to be the \"gzip\" compression level (between 1 and 9),\nbut the use of constants is preferred:\n\n# write a gzip compressed file\n$tar->write( 'out.tgz', COMPRESSGZIP );\n\n# write a bzip compressed file\n$tar->write( 'out.tbz', COMPRESSBZIP );\n\n# write a xz compressed file\n$tar->write( 'out.txz', COMPRESSXZ );\n\nNote that when you pass in a filehandle, the compression argument is ignored, as all files are\nprinted verbatim to your filehandle. If you wish to enable compression with filehandles, use an\n\"IO::Zlib\", \"IO::Compress::Bzip2\" or \"IO::Compress::Xz\" filehandle instead.\n\nThe third argument is an optional prefix. All files will be tucked away in the directory you\nspecify as prefix. So if you have files 'a' and 'b' in your archive, and you specify 'foo' as\nprefix, they will be written to the archive as 'foo/a' and 'foo/b'.\n\nIf no arguments are given, \"write\" returns the entire formatted archive as a string, which could\nbe useful if you'd like to stuff the archive into a socket or a pipe to gzip or something.\n\n$tar->addfiles( @filenamelist )\nTakes a list of filenames and adds them to the in-memory archive.\n\nThe path to the file is automatically converted to a Unix like equivalent for use in the\narchive, and, if on MacOS, the file's modification time is converted from the MacOS epoch to the\nUnix epoch. So tar archives created on MacOS with Archive::Tar can be read both with *tar* on\nUnix and applications like *suntar* or *Stuffit Expander* on MacOS.\n\nBe aware that the file's type/creator and resource fork will be lost, which is usually what you\nwant in cross-platform archives.\n\nInstead of a filename, you can also pass it an existing \"Archive::Tar::File\" object from, for\nexample, another archive. The object will be clone, and effectively be a copy of the original,\nnot an alias.\n\nReturns a list of \"Archive::Tar::File\" objects that were just added.\n\n$tar->adddata ( $filename, $data, [$opthashref] )\nTakes a filename, a scalar full of data and optionally a reference to a hash with specific\noptions.\n\nWill add a file to the in-memory archive, with name $filename and content $data. Specific\nproperties can be set using $opthashref. The following list of properties is supported: name,\nsize, mtime (last modified date), mode, uid, gid, linkname, uname, gname, devmajor, devminor,\nprefix, type. (On MacOS, the file's path and modification times are converted to Unix\nequivalents.)\n\nValid values for the file type are the following constants defined by Archive::Tar::Constant:\n\nFILE\nRegular file.\n\nHARDLINK\nSYMLINK\nHard and symbolic (\"soft\") links; linkname should specify target.\n\nCHARDEV\nBLOCKDEV\nCharacter and block devices. devmajor and devminor should specify the major and minor device\nnumbers.\n\nDIR Directory.\n\nFIFO\nFIFO (named pipe).\n\nSOCKET\nSocket.\n\nReturns the \"Archive::Tar::File\" object that was just added, or \"undef\" on failure.\n\n$tar->error( [$BOOL] )\nReturns the current error string (usually, the last error reported). If a true value was\nspecified, it will give the \"Carp::longmess\" equivalent of the error, in effect giving you a\nstacktrace.\n\nFor backwards compatibility, this error is also available as $Archive::Tar::error although it is\nmuch recommended you use the method call instead.\n\n$tar->setcwd( $cwd );\n\"Archive::Tar\" needs to know the current directory, and it will run \"Cwd::cwd()\" *every* time it\nextracts a *relative* entry from the tarfile and saves it in the file system. (As of version\n1.30, however, \"Archive::Tar\" will use the speed optimization described below automatically, so\nit's only relevant if you're using \"extractfile()\").\n\nSince \"Archive::Tar\" doesn't change the current directory internally while it is extracting the\nitems in a tarball, all calls to \"Cwd::cwd()\" can be avoided if we can guarantee that the\ncurrent directory doesn't get changed externally.\n\nTo use this performance boost, set the current directory via\n\nuse Cwd;\n$tar->setcwd( cwd() );\n\nonce before calling a function like \"extractfile\" and \"Archive::Tar\" will use the current\ndirectory setting from then on and won't call \"Cwd::cwd()\" internally.\n\nTo switch back to the default behaviour, use\n\n$tar->setcwd( undef );\n\nand \"Archive::Tar\" will call \"Cwd::cwd()\" internally again.\n\nIf you're using \"Archive::Tar\"'s \"extract()\" method, \"setcwd()\" will be called for you.\n",
            "subsections": []
        },
        "Class Methods": {
            "content": "Archive::Tar->createarchive($file, $compressed, @filelist)\nCreates a tar file from the list of files provided. The first argument can either be the name of\nthe tar file to create or a reference to an open file handle (e.g. a GLOB reference).\n\nThe second argument is used to indicate compression. You can compress using \"gzip\", \"bzip2\" or\n\"xz\". If you pass a digit, it's assumed to be the \"gzip\" compression level (between 1 and 9),\nbut the use of constants is preferred:\n\n# write a gzip compressed file\nArchive::Tar->createarchive( 'out.tgz', COMPRESSGZIP, @filelist );\n\n# write a bzip compressed file\nArchive::Tar->createarchive( 'out.tbz', COMPRESSBZIP, @filelist );\n\n# write a xz compressed file\nArchive::Tar->createarchive( 'out.txz', COMPRESSXZ, @filelist );\n\nNote that when you pass in a filehandle, the compression argument is ignored, as all files are\nprinted verbatim to your filehandle. If you wish to enable compression with filehandles, use an\n\"IO::Zlib\", \"IO::Compress::Bzip2\" or \"IO::Compress::Xz\" filehandle instead.\n\nThe remaining arguments list the files to be included in the tar file. These files must all\nexist. Any files which don't exist or can't be read are silently ignored.\n\nIf the archive creation fails for any reason, \"createarchive\" will return false. Please use the\n\"error\" method to find the cause of the failure.\n\nNote that this method does not write \"on the fly\" as it were; it still reads all the files into\nmemory before writing out the archive. Consult the FAQ below if this is a problem.\n\nArchive::Tar->iter( $filename, [ $compressed, {opt => $val} ] )\nReturns an iterator function that reads the tar file without loading it all in memory. Each time\nthe function is called it will return the next file in the tarball. The files are returned as\n\"Archive::Tar::File\" objects. The iterator function returns the empty list once it has exhausted\nthe files contained.\n\nThe second argument can be a hash reference with options, which are identical to the arguments\npassed to \"read()\".\n\nExample usage:\n\nmy $next = Archive::Tar->iter( \"example.tar.gz\", 1, {filter => qr/\\.pm$/} );\n\nwhile( my $f = $next->() ) {\nprint $f->name, \"\\n\";\n\n$f->extract or warn \"Extraction failed\";\n\n# ....\n}\n\nArchive::Tar->listarchive($file, $compressed, [\\@properties])\nReturns a list of the names of all the files in the archive. The first argument can either be\nthe name of the tar file to list or a reference to an open file handle (e.g. a GLOB reference).\n\nIf \"listarchive()\" is passed an array reference as its third argument it returns a list of hash\nreferences containing the requested properties of each file. The following list of properties is\nsupported: fullpath, name, size, mtime (last modified date), mode, uid, gid, linkname, uname,\ngname, devmajor, devminor, prefix, type.\n\nSee \"Archive::Tar::File\" for details about supported properties.\n\nPassing an array reference containing only one element, 'name', is special cased to return a\nlist of names rather than a list of hash references.\n\nArchive::Tar->extractarchive($file, $compressed)\nExtracts the contents of the tar file. The first argument can either be the name of the tar file\nto create or a reference to an open file handle (e.g. a GLOB reference). All relative paths in\nthe tar file will be created underneath the current working directory.\n\n\"extractarchive\" will return a list of files it extracted. If the archive extraction fails for\nany reason, \"extractarchive\" will return false. Please use the \"error\" method to find the cause\nof the failure.\n\n$bool = Archive::Tar->hasiostring\nReturns true if we currently have \"IO::String\" support loaded.\n\nEither \"IO::String\" or \"perlio\" support is needed to support writing stringified archives.\nCurrently, \"perlio\" is the preferred method, if available.\n\nSee the \"GLOBAL VARIABLES\" section to see how to change this preference.\n\n$bool = Archive::Tar->hasperlio\nReturns true if we currently have \"perlio\" support loaded.\n\nThis requires \"perl-5.8\" or higher, compiled with \"perlio\"\n\nEither \"IO::String\" or \"perlio\" support is needed to support writing stringified archives.\nCurrently, \"perlio\" is the preferred method, if available.\n\nSee the \"GLOBAL VARIABLES\" section to see how to change this preference.\n\n$bool = Archive::Tar->haszlibsupport\nReturns true if \"Archive::Tar\" can extract \"zlib\" compressed archives\n\n$bool = Archive::Tar->hasbzip2support\nReturns true if \"Archive::Tar\" can extract \"bzip2\" compressed archives\n\n$bool = Archive::Tar->hasxzsupport\nReturns true if \"Archive::Tar\" can extract \"xz\" compressed archives\n\nArchive::Tar->canhandlecompressedfiles\nA simple checking routine, which will return true if \"Archive::Tar\" is able to uncompress\ncompressed archives on the fly with \"IO::Zlib\", \"IO::Compress::Bzip2\" and \"IO::Compress::Xz\" or\nfalse if not both are installed.\n\nYou can use this as a shortcut to determine whether \"Archive::Tar\" will do what you think before\npassing compressed archives to its \"read\" method.\n",
            "subsections": []
        },
        "GLOBAL VARIABLES": {
            "content": "$Archive::Tar::FOLLOWSYMLINK\nSet this variable to 1 to make \"Archive::Tar\" effectively make a copy of the file when\nextracting. Default is 0, which means the symlink stays intact. Of course, you will have to pack\nthe file linked to as well.\n\nThis option is checked when you write out the tarfile using \"write\" or \"createarchive\".\n\nThis works just like \"/bin/tar\"'s \"-h\" option.\n\n$Archive::Tar::CHOWN\nBy default, \"Archive::Tar\" will try to \"chown\" your files if it is able to. In some cases, this\nmay not be desired. In that case, set this variable to 0 to disable \"chown\"-ing, even if it were\npossible.\n\nThe default is 1.\n\n$Archive::Tar::CHMOD\nBy default, \"Archive::Tar\" will try to \"chmod\" your files to whatever mode was specified for the\nparticular file in the archive. In some cases, this may not be desired. In that case, set this\nvariable to 0 to disable \"chmod\"-ing.\n\nThe default is 1.\n\n$Archive::Tar::SAMEPERMISSIONS\nWhen, $Archive::Tar::CHMOD is enabled, this setting controls whether the permissions on files\nfrom the archive are used without modification of if they are filtered by removing any setid\nbits and applying the current umask.\n\nThe default is 1 for the root user and 0 for normal users.\n\n$Archive::Tar::DONOTUSEPREFIX\nBy default, \"Archive::Tar\" will try to put paths that are over 100 characters in the \"prefix\"\nfield of your tar header, as defined per POSIX-standard. However, some (older) tar programs do\nnot implement this spec. To retain compatibility with these older or non-POSIX compliant\nversions, you can set the $DONOTUSEPREFIX variable to a true value, and \"Archive::Tar\" will\nuse an alternate way of dealing with paths over 100 characters by using the \"GNU Extended\nHeader\" feature.\n\nNote that clients who do not support the \"GNU Extended Header\" feature will not be able to read\nthese archives. Such clients include tars on \"Solaris\", \"Irix\" and \"AIX\".\n\nThe default is 0.\n\n$Archive::Tar::DEBUG\nSet this variable to 1 to always get the \"Carp::longmess\" output of the warnings, instead of the\nregular \"carp\". This is the same message you would get by doing:\n\n$tar->error(1);\n\nDefaults to 0.\n\n$Archive::Tar::WARN\nSet this variable to 0 if you do not want any warnings printed. Personally I recommend against\ndoing this, but people asked for the option. Also, be advised that this is of course not\nthreadsafe.\n\nDefaults to 1.\n\n$Archive::Tar::error\nHolds the last reported error. Kept for historical reasons, but its use is very much\ndiscouraged. Use the \"error()\" method instead:\n\nwarn $tar->error unless $tar->extract;\n\nNote that in older versions of this module, the \"error()\" method would return an effectively\nglobal value even when called an instance method as above. This has since been fixed, and\nmultiple instances of \"Archive::Tar\" now have separate error strings.\n\n$Archive::Tar::INSECUREEXTRACTMODE\nThis variable indicates whether \"Archive::Tar\" should allow files to be extracted outside their\ncurrent working directory.\n\nAllowing this could have security implications, as a malicious tar archive could alter or\nreplace any file the extracting user has permissions to. Therefor, the default is to not allow\ninsecure extractions.\n\nIf you trust the archive, or have other reasons to allow the archive to write files outside your\ncurrent working directory, set this variable to \"true\".\n\nNote that this is a backwards incompatible change from version 1.36 and before.\n\n$Archive::Tar::HASPERLIO\nThis variable holds a boolean indicating if we currently have \"perlio\" support loaded. This will\nbe enabled for any perl greater than 5.8 compiled with \"perlio\".\n\nIf you feel strongly about disabling it, set this variable to \"false\". Note that you will then\nneed \"IO::String\" installed to support writing stringified archives.\n\nDon't change this variable unless you really know what you're doing.\n\n$Archive::Tar::HASIOSTRING\nThis variable holds a boolean indicating if we currently have \"IO::String\" support loaded. This\nwill be enabled for any perl that has a loadable \"IO::String\" module.\n\nIf you feel strongly about disabling it, set this variable to \"false\". Note that you will then\nneed \"perlio\" support from your perl to be able to write stringified archives.\n\nDon't change this variable unless you really know what you're doing.\n\n$Archive::Tar::ZEROPADNUMBERS\nThis variable holds a boolean indicating if we will create zero padded numbers for \"size\",\n\"mtime\" and \"checksum\". The default is 0, indicating that we will create space padded numbers.\nAdded for compatibility with \"busybox\" implementations.\n",
            "subsections": [
                {
                    "name": "Tuning the way RESOLVESYMLINK will works",
                    "content": "You can tune the behaviour by setting the $Archive::Tar::RESOLVESYMLINK variable,\nor $ENV{PERL5ATRESOLVESYMLINK} before loading the module Archive::Tar.\n\nValues can be one of the following:\n\nnone\nDisable this mechanism and failed as it was in previous version (<1.88)\n\nspeed (default)\nIf you prefer speed\nthis will read again the whole archive using read() so all entries\nwill be available\n\nmemory\nIf you prefer memory\n\nLimitation\n\nIt won't work for terminal, pipe or sockets or every non seekable source.\n"
                }
            ]
        },
        "FAQ": {
            "content": "What's the minimum perl version required to run Archive::Tar?\nYou will need perl version 5.00503 or newer.\n\nIsn't Archive::Tar slow?\nYes it is. It's pure perl, so it's a lot slower then your \"/bin/tar\" However, it's very\nportable. If speed is an issue, consider using \"/bin/tar\" instead.\n\nIsn't Archive::Tar heavier on memory than /bin/tar?\nYes it is, see previous answer. Since \"Compress::Zlib\" and therefore \"IO::Zlib\" doesn't\nsupport \"seek\" on their filehandles, there is little choice but to read the archive into\nmemory. This is ok if you want to do in-memory manipulation of the archive.\n\nIf you just want to extract, use the \"extractarchive\" class method instead. It will\noptimize and write to disk immediately.\n\nAnother option is to use the \"iter\" class method to iterate over the files in the tarball\nwithout reading them all in memory at once.\n\nCan you lazy-load data instead?\nIn some cases, yes. You can use the \"iter\" class method to iterate over the files in the\ntarball without reading them all in memory at once.\n\nHow much memory will an X kb tar file need?\nProbably more than X kb, since it will all be read into memory. If this is a problem, and\nyou don't need to do in memory manipulation of the archive, consider using the \"iter\" class\nmethod, or \"/bin/tar\" instead.\n\nWhat do you do with unsupported filetypes in an archive?\n\"Unix\" has a few filetypes that aren't supported on other platforms, like \"Win32\". If we\nencounter a \"hardlink\" or \"symlink\" we'll just try to make a copy of the original file,\nrather than throwing an error.\n\nThis does require you to read the entire archive in to memory first, since otherwise we\nwouldn't know what data to fill the copy with. (This means that you cannot use the class\nmethods, including \"iter\" on archives that have incompatible filetypes and still expect\nthings to work).\n\nFor other filetypes, like \"chardevs\" and \"blockdevs\" we'll warn that the extraction of this\nparticular item didn't work.\n\nI'm using WinZip, or some other non-POSIX client, and files are not being extracted properly!\nBy default, \"Archive::Tar\" is in a completely POSIX-compatible mode, which uses the\nPOSIX-specification of \"tar\" to store files. For paths greater than 100 characters, this is\ndone using the \"POSIX header prefix\". Non-POSIX-compatible clients may not support this part\nof the specification, and may only support the \"GNU Extended Header\" functionality. To\nfacilitate those clients, you can set the $Archive::Tar::DONOTUSEPREFIX variable to\n\"true\". See the \"GLOBAL VARIABLES\" section for details on this variable.\n\nNote that GNU tar earlier than version 1.14 does not cope well with the \"POSIX header\nprefix\". If you use such a version, consider setting the $Archive::Tar::DONOTUSEPREFIX\nvariable to \"true\".\n\nHow do I extract only files that have property X from an archive?\nSometimes, you might not wish to extract a complete archive, just the files that are\nrelevant to you, based on some criteria.\n\nYou can do this by filtering a list of \"Archive::Tar::File\" objects based on your criteria.\nFor example, to extract only files that have the string \"foo\" in their title, you would use:\n\n$tar->extract(\ngrep { $->fullpath =~ /foo/ } $tar->getfiles\n);\n\nThis way, you can filter on any attribute of the files in the archive. Consult the\n\"Archive::Tar::File\" documentation on how to use these objects.\n\nHow do I access .tar.Z files?\nThe \"Archive::Tar\" module can optionally use \"Compress::Zlib\" (via the \"IO::Zlib\" module) to\naccess tar files that have been compressed with \"gzip\". Unfortunately tar files compressed\nwith the Unix \"compress\" utility cannot be read by \"Compress::Zlib\" and so cannot be\ndirectly accesses by \"Archive::Tar\".\n\nIf the \"uncompress\" or \"gunzip\" programs are available, you can use one of these workarounds\nto read \".tar.Z\" files from \"Archive::Tar\"\n\nFirstly with \"uncompress\"\n\nuse Archive::Tar;\n\nopen F, \"uncompress -c $filename |\";\nmy $tar = Archive::Tar->new(*F);\n...\n\nand this with \"gunzip\"\n\nuse Archive::Tar;\n\nopen F, \"gunzip -c $filename |\";\nmy $tar = Archive::Tar->new(*F);\n...\n\nSimilarly, if the \"compress\" program is available, you can use this to write a \".tar.Z\" file\n\nuse Archive::Tar;\nuse IO::File;\n\nmy $fh = IO::File->new( \"| compress -c >$filename\" );\nmy $tar = Archive::Tar->new();\n...\n$tar->write($fh);\n$fh->close ;\n\nHow do I handle Unicode strings?\n\"Archive::Tar\" uses byte semantics for any files it reads from or writes to disk. This is\nnot a problem if you only deal with files and never look at their content or work solely\nwith byte strings. But if you use Unicode strings with character semantics, some additional\nsteps need to be taken.\n\nFor example, if you add a Unicode string like\n\n# Problem\n$tar->adddata('file.txt', \"Euro: \\x{20AC}\");\n\nthen there will be a problem later when the tarfile gets written out to disk via\n\"$tar->write()\":\n\nWide character in print at .../Archive/Tar.pm line 1014.\n\nThe data was added as a Unicode string and when writing it out to disk, the \":utf8\" line\ndiscipline wasn't set by \"Archive::Tar\", so Perl tried to convert the string to ISO-8859 and\nfailed. The written file now contains garbage.\n\nFor this reason, Unicode strings need to be converted to UTF-8-encoded bytestrings before\nthey are handed off to \"adddata()\":\n\nuse Encode;\nmy $data = \"Accented character: \\x{20AC}\";\n$data = encode('utf8', $data);\n\n$tar->adddata('file.txt', $data);\n\nA opposite problem occurs if you extract a UTF8-encoded file from a tarball. Using\n\"getcontent()\" on the \"Archive::Tar::File\" object will return its content as a bytestring,\nnot as a Unicode string.\n\nIf you want it to be a Unicode string (because you want character semantics with operations\nlike regular expression matching), you need to decode the UTF8-encoded content and have Perl\nconvert it into a Unicode string:\n\nuse Encode;\nmy $data = $tar->getcontent();\n\n# Make it a Unicode string\n$data = decode('utf8', $data);\n\nThere is no easy way to provide this functionality in \"Archive::Tar\", because a tarball can\ncontain many files, and each of which could be encoded in a different way.\n",
            "subsections": []
        },
        "CAVEATS": {
            "content": "The AIX tar does not fill all unused space in the tar archive with 0x00. This sometimes leads to\nwarning messages from \"Archive::Tar\".\n\nInvalid header block at offset nnn\n\nA fix for that problem is scheduled to be released in the following levels of AIX, all of which\nshould be coming out in the 4th quarter of 2009:\n\nAIX 5.3 TL7 SP10\nAIX 5.3 TL8 SP8\nAIX 5.3 TL9 SP5\nAIX 5.3 TL10 SP2\n\nAIX 6.1 TL0 SP11\nAIX 6.1 TL1 SP7\nAIX 6.1 TL2 SP6\nAIX 6.1 TL3 SP3\n\nThe IBM APAR number for this problem is IZ50240 (Reported component ID: 5765G0300 / AIX 5.3). It\nis possible to get an ifix for that problem. If you need an ifix please contact your local IBM\nAIX support.\n",
            "subsections": []
        },
        "TODO": {
            "content": "Check if passed in handles are open for read/write\nCurrently I don't know of any portable pure perl way to do this. Suggestions welcome.\n\nAllow archives to be passed in as string\nCurrently, we only allow opened filehandles or filenames, but not strings. The internals\nwould need some reworking to facilitate stringified archives.\n\nFacilitate processing an opened filehandle of a compressed archive\nCurrently, we only support this if the filehandle is an IO::Zlib object. Environments, like\napache, will present you with an opened filehandle to an uploaded file, which might be a\ncompressed archive.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "The GNU tar specification\n\"http://www.gnu.org/software/tar/manual/tar.html\"\n\nThe PAX format specification\nThe specification which tar derives from; \"\nhttp://www.opengroup.org/onlinepubs/007904975/utilities/pax.html\"\n\nA comparison of GNU and POSIX tar standards; \"http://www.delorie.com/gnu/docs/tar/tar114.html\"\nGNU tar intends to switch to POSIX compatibility\nGNU Tar authors have expressed their intention to become completely POSIX-compatible;\n\"http://www.gnu.org/software/tar/manual/htmlnode/Formats.html\"\n\nA Comparison between various tar implementations\nLists known issues and incompatibilities;\n\"http://gd.tuwien.ac.at/utils/archivers/star/README.otherbugs\"\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "This module by Jos Boumans <kane@cpan.org>.\n\nPlease reports bugs to <bug-archive-tar@rt.cpan.org>.\n",
            "subsections": []
        },
        "ACKNOWLEDGEMENTS": {
            "content": "Thanks to Sean Burke, Chris Nandor, Chip Salzenberg, Tim Heaney, Gisle Aas, Rainer Tammer and\nespecially Andrew Savige for their help and suggestions.\n",
            "subsections": []
        },
        "COPYRIGHT": {
            "content": "This module is copyright (c) 2002 - 2009 Jos Boumans <kane@cpan.org>. All rights reserved.\n\nThis library is free software; you may redistribute and/or modify it under the same terms as\nPerl itself.\n",
            "subsections": []
        }
    },
    "summary": "Archive::Tar - module for manipulations of tar archives",
    "flags": [],
    "examples": [],
    "see_also": []
}