{
    "mode": "perldoc",
    "parameter": "Archive::Tar",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Archive%3A%3ATar/json",
    "generated": "2026-05-30T08:17:16Z",
    "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\nfiles. It provides class methods for quick and easy files handling while\nalso allowing for the creation of tar file objects for custom\nmanipulation. If you have the IO::Zlib module installed, Archive::Tar\nwill also support compressed or gzipped tar files.\n\nAn object of class Archive::Tar represents a .tar(.gz) archive full of\nfiles and things.\n",
            "subsections": []
        },
        "Object Methods": {
            "content": "Archive::Tar->new( [$file, $compressed] )\nReturns a new Tar object. If given any arguments, \"new()\" calls the\n\"read()\" method automatically, passing on the arguments provided to the\n\"read()\" method.\n\nIf \"new()\" is invoked with arguments and the \"read()\" method fails for\nany reason, \"new()\" returns undef.\n\n$tar->read ( $filename|$handle, [$compressed, {opt => 'val'}] )\nRead the given tar file into memory. The first argument can either be\nthe name of a file or a reference to an already open filehandle (or an\nIO::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\nbackwards compatibility. Archive::Tar now looks at the file magic to\ndetermine what class should be used to open the file and will\ntransparently Do The Right Thing.\n\nArchive::Tar will warn if you try to pass a bzip2 / xz compressed file\nand the IO::Uncompress::Bunzip2 / IO::Uncompress::UnXz are not available\nand simply return.\n\nNote that you can currently not pass a \"gzip\" compressed filehandle,\nwhich is not opened with \"IO::Zlib\", a \"bzip2\" compressed filehandle,\nwhich is not opened with \"IO::Uncompress::Bunzip2\", a \"xz\" compressed\nfilehandle, which is not opened with \"IO::Uncompress::UnXz\", nor a\nstring containing the full archive information (either compressed or\nuncompressed). These are worth while features, but not currently\nimplemented. See the \"TODO\" section.\n\nThe third argument can be a hash reference with options. Note that all\noptions are case-sensitive.\n\nlimit\nDo not read more than \"limit\" files. This is useful if you have very\nbig archives, and are only interested in the first few files.\n\nfilter\nCan be set to a regular expression. Only files with names that match\nthe expression will be read.\n\nmd5 Set to 1 and the md5sum of files will be returned (instead of file\ndata) my $iter = Archive::Tar->iter( $file, 1, {md5 => 1} ); while(\nmy $f = $iter->() ) { print $f->data . \"\\t\" . $f->fullpath . $/; }\n\nextract\nIf set to true, immediately extract entries when reading them. This\ngives you the same memory break as the \"extractarchive\" function.\nNote however that entries will not be read into memory, but written\nstraight 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\nconsult the Archive::Tar::File documentation for details.\n\nReturns the number of files read in scalar context, and a list of\n\"Archive::Tar::File\" objects in list context.\n\n$tar->containsfile( $filename )\nCheck if the archive contains a certain file. It will return true if the\nfile is in the archive, false otherwise.\n\nNote however, that this function does an exact match using \"eq\" on the\nfull path. So it cannot compensate for case-insensitive file- systems or\ncompare 2 paths to see if they would point to the same underlying file.\n\n$tar->extract( [@filenames] )\nWrite files whose names are equivalent to any of the names in @filenames\nto disk, creating subdirectories as necessary. This might not work too\nwell under VMS. Under MacPerl, the file's modification time will be\nconverted to the MacOS zero of time, and appropriate conversions will be\ndone to the path. However, the length of each element of the path is not\ninspected to see whether it's longer than MacOS currently allows (32\ncharacters).\n\nIf \"extract\" is called without a list of file names, the entire contents\nof the archive are extracted.\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\ndisk. Optionally takes a second parameter, which is the full native path\n(including filename) the entry will be written to.\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\nreturns a list of hash references containing the requested properties of\neach file. The following list of properties is supported: name, size,\nmtime (last modified date), mode, uid, gid, linkname, uname, gname,\ndevmajor, devminor, prefix.\n\nPassing an array reference containing only one element, 'name', is\nspecial cased to return a list of names rather than a list of hash\nreferences, making it equivalent to calling \"listfiles\" without\narguments.\n\n$tar->getfiles( [@filenames] )\nReturns the \"Archive::Tar::File\" objects matching the filenames\nprovided. If no filename list was passed, all \"Archive::Tar::File\"\nobjects in the current Tar object are returned.\n\nPlease refer to the \"Archive::Tar::File\" documentation on how to handle\nthese 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\nstandard, all files in the archive 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\nthe in-memory archive. Returns a list of \"Archive::Tar::File\" objects\nthat remain.\n\n$tar->clear\n\"clear\" clears the current in-memory archive. This effectively gives you\na 'blank' object, ready to be filled again. Note that \"clear\" only has\neffect 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\nthe name of a file or a reference to an already open filehandle (a GLOB\nreference).\n\nThe second argument is used to indicate compression. You can compress\nusing \"gzip\", \"bzip2\" or \"xz\". If you pass a digit, it's assumed to be\nthe \"gzip\" compression level (between 1 and 9), but the use of constants\nis 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\nignored, as all files are printed verbatim to your filehandle. If you\nwish to enable compression with filehandles, use an \"IO::Zlib\",\n\"IO::Compress::Bzip2\" or \"IO::Compress::Xz\" filehandle instead.\n\nThe third argument is an optional prefix. All files will be tucked away\nin the directory you specify as prefix. So if you have files 'a' and 'b'\nin your archive, and you specify 'foo' as prefix, they will be written\nto the archive as 'foo/a' and 'foo/b'.\n\nIf no arguments are given, \"write\" returns the entire formatted archive\nas a string, which could be useful if you'd like to stuff the archive\ninto 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\nequivalent for use in the archive, and, if on MacOS, the file's\nmodification time is converted from the MacOS epoch to the Unix epoch.\nSo tar archives created on MacOS with Archive::Tar can be read both with\n*tar* on Unix and applications like *suntar* or *Stuffit Expander* on\nMacOS.\n\nBe aware that the file's type/creator and resource fork will be lost,\nwhich is usually what you want in cross-platform archives.\n\nInstead of a filename, you can also pass it an existing\n\"Archive::Tar::File\" object from, for example, another archive. The\nobject will be clone, and effectively be a copy of the original, not an\nalias.\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\nhash with specific options.\n\nWill add a file to the in-memory archive, with name $filename and\ncontent $data. Specific properties can be set using $opthashref. The\nfollowing list of properties is supported: name, size, mtime (last\nmodified date), mode, uid, gid, linkname, uname, gname, devmajor,\ndevminor, prefix, type. (On MacOS, the file's path and modification\ntimes are converted to Unix equivalents.)\n\nValid values for the file type are the following constants defined by\nArchive::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\nthe major and minor device numbers.\n\nDIR Directory.\n\nFIFO\nFIFO (named pipe).\n\nSOCKET\nSocket.\n\nReturns the \"Archive::Tar::File\" object that was just added, or \"undef\"\non failure.\n\n$tar->error( [$BOOL] )\nReturns the current error string (usually, the last error reported). If\na true value was specified, it will give the \"Carp::longmess\" equivalent\nof the error, in effect giving you a stacktrace.\n\nFor backwards compatibility, this error is also available as\n$Archive::Tar::error although it is much recommended you use the method\ncall instead.\n\n$tar->setcwd( $cwd );\n\"Archive::Tar\" needs to know the current directory, and it will run\n\"Cwd::cwd()\" *every* time it extracts a *relative* entry from the\ntarfile and saves it in the file system. (As of version 1.30, however,\n\"Archive::Tar\" will use the speed optimization described below\nautomatically, so it's only relevant if you're using \"extractfile()\").\n\nSince \"Archive::Tar\" doesn't change the current directory internally\nwhile it is extracting the items in a tarball, all calls to \"Cwd::cwd()\"\ncan be avoided if we can guarantee that the current directory doesn't\nget 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\"\nwill use the current directory setting from then on and won't call\n\"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\ncalled 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\ncan either be the name of the tar file to create or a reference to an\nopen file handle (e.g. a GLOB reference).\n\nThe second argument is used to indicate compression. You can compress\nusing \"gzip\", \"bzip2\" or \"xz\". If you pass a digit, it's assumed to be\nthe \"gzip\" compression level (between 1 and 9), but the use of constants\nis 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\nignored, as all files are printed verbatim to your filehandle. If you\nwish to enable compression with filehandles, use an \"IO::Zlib\",\n\"IO::Compress::Bzip2\" or \"IO::Compress::Xz\" filehandle instead.\n\nThe remaining arguments list the files to be included in the tar file.\nThese files must all exist. Any files which don't exist or can't be read\nare silently ignored.\n\nIf the archive creation fails for any reason, \"createarchive\" will\nreturn false. Please use the \"error\" method to find the cause of the\nfailure.\n\nNote that this method does not write \"on the fly\" as it were; it still\nreads all the files into memory before writing out the archive. Consult\nthe 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\nall in memory. Each time the function is called it will return the next\nfile in the tarball. The files are returned as \"Archive::Tar::File\"\nobjects. The iterator function returns the empty list once it has\nexhausted the files contained.\n\nThe second argument can be a hash reference with options, which are\nidentical to the arguments passed 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\nargument can either be the name of the tar file to list or a reference\nto an open file handle (e.g. a GLOB reference).\n\nIf \"listarchive()\" is passed an array reference as its third argument\nit returns a list of hash references containing the requested properties\nof each file. The following list of properties is supported: fullpath,\nname, 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\nspecial cased to return a list of names rather than a list of hash\nreferences.\n\nArchive::Tar->extractarchive($file, $compressed)\nExtracts the contents of the tar file. The first argument can either be\nthe name of the tar file to create or a reference to an open file handle\n(e.g. a GLOB reference). All relative paths in the tar file will be\ncreated underneath the current working directory.\n\n\"extractarchive\" will return a list of files it extracted. If the\narchive extraction fails for any reason, \"extractarchive\" will return\nfalse. Please use the \"error\" method to find the cause of 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\nstringified archives. Currently, \"perlio\" is the preferred method, if\navailable.\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\nstringified archives. Currently, \"perlio\" is the preferred method, if\navailable.\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\nable to uncompress compressed archives on the fly with \"IO::Zlib\",\n\"IO::Compress::Bzip2\" and \"IO::Compress::Xz\" or false if not both are\ninstalled.\n\nYou can use this as a shortcut to determine whether \"Archive::Tar\" will\ndo what you think before passing compressed archives to its \"read\"\nmethod.\n",
            "subsections": []
        },
        "GLOBAL VARIABLES": {
            "content": "$Archive::Tar::FOLLOWSYMLINK\nSet this variable to 1 to make \"Archive::Tar\" effectively make a copy of\nthe file when extracting. Default is 0, which means the symlink stays\nintact. Of course, you will have to pack the file linked to as well.\n\nThis option is checked when you write out the tarfile using \"write\" or\n\"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\nto. In some cases, this may not be desired. In that case, set this\nvariable to 0 to disable \"chown\"-ing, even if it were possible.\n\nThe default is 1.\n\n$Archive::Tar::CHMOD\nBy default, \"Archive::Tar\" will try to \"chmod\" your files to whatever\nmode was specified for the particular file in the archive. In some\ncases, this may not be desired. In that case, set this variable to 0 to\ndisable \"chmod\"-ing.\n\nThe default is 1.\n\n$Archive::Tar::SAMEPERMISSIONS\nWhen, $Archive::Tar::CHMOD is enabled, this setting controls whether the\npermissions on files from the archive are used without modification of\nif they are filtered by removing any setid bits and applying the current\numask.\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\ncharacters in the \"prefix\" field of your tar header, as defined per\nPOSIX-standard. However, some (older) tar programs do not implement this\nspec. To retain compatibility with these older or non-POSIX compliant\nversions, you can set the $DONOTUSEPREFIX variable to a true value,\nand \"Archive::Tar\" will use an alternate way of dealing with paths over\n100 characters by using the \"GNU Extended Header\" feature.\n\nNote that clients who do not support the \"GNU Extended Header\" feature\nwill not be able to read these archives. Such clients include tars on\n\"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\nwarnings, instead of the regular \"carp\". This is the same message you\nwould 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.\nPersonally I recommend against doing this, but people asked for the\noption. Also, be advised that this is of course not threadsafe.\n\nDefaults to 1.\n\n$Archive::Tar::error\nHolds the last reported error. Kept for historical reasons, but its use\nis very much discouraged. 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\nreturn an effectively global value even when called an instance method\nas above. This has since been fixed, and multiple instances of\n\"Archive::Tar\" now have separate error strings.\n\n$Archive::Tar::INSECUREEXTRACTMODE\nThis variable indicates whether \"Archive::Tar\" should allow files to be\nextracted outside their current working directory.\n\nAllowing this could have security implications, as a malicious tar\narchive could alter or replace any file the extracting user has\npermissions to. Therefor, the default is to not allow insecure\nextractions.\n\nIf you trust the archive, or have other reasons to allow the archive to\nwrite files outside your current working directory, set this variable to\n\"true\".\n\nNote that this is a backwards incompatible change from version 1.36 and\nbefore.\n\n$Archive::Tar::HASPERLIO\nThis variable holds a boolean indicating if we currently have \"perlio\"\nsupport loaded. This will be enabled for any perl greater than 5.8\ncompiled with \"perlio\".\n\nIf you feel strongly about disabling it, set this variable to \"false\".\nNote that you will then need \"IO::String\" installed to support writing\nstringified 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\n\"IO::String\" support loaded. This will be enabled for any perl that has\na loadable \"IO::String\" module.\n\nIf you feel strongly about disabling it, set this variable to \"false\".\nNote that you will then need \"perlio\" support from your perl to be able\nto 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\nnumbers for \"size\", \"mtime\" and \"checksum\". The default is 0, indicating\nthat we will create space padded numbers. Added for compatibility with\n\"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\"\nHowever, it's very portable. If speed is an issue, consider using\n\"/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\n\"IO::Zlib\" doesn't support \"seek\" on their filehandles, there is\nlittle choice but to read the archive into memory. This is ok if you\nwant to do in-memory manipulation of the archive.\n\nIf you just want to extract, use the \"extractarchive\" class method\ninstead. It will optimize and write to disk immediately.\n\nAnother option is to use the \"iter\" class method to iterate over the\nfiles in the tarball without 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\nover the files in the tarball without reading them all in memory at\nonce.\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\nthis is a problem, and you don't need to do in memory manipulation\nof the archive, consider using the \"iter\" class method, or\n\"/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,\nlike \"Win32\". If we encounter a \"hardlink\" or \"symlink\" we'll just\ntry to make a copy of the original file, rather than throwing an\nerror.\n\nThis does require you to read the entire archive in to memory first,\nsince otherwise we wouldn't know what data to fill the copy with.\n(This means that you cannot use the class methods, including \"iter\"\non archives that have incompatible filetypes and still expect things\nto work).\n\nFor other filetypes, like \"chardevs\" and \"blockdevs\" we'll warn that\nthe extraction of this particular item didn't work.\n\nI'm using WinZip, or some other non-POSIX client, and files are not\nbeing extracted properly!\nBy default, \"Archive::Tar\" is in a completely POSIX-compatible mode,\nwhich uses the POSIX-specification of \"tar\" to store files. For\npaths greater than 100 characters, this is done using the \"POSIX\nheader prefix\". Non-POSIX-compatible clients may not support this\npart of the specification, and may only support the \"GNU Extended\nHeader\" functionality. To facilitate those clients, you can set the\n$Archive::Tar::DONOTUSEPREFIX variable to \"true\". See the \"GLOBAL\nVARIABLES\" section for details on this variable.\n\nNote that GNU tar earlier than version 1.14 does not cope well with\nthe \"POSIX header prefix\". If you use such a version, consider\nsetting the $Archive::Tar::DONOTUSEPREFIX variable 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\nthe files that are relevant to you, based on some criteria.\n\nYou can do this by filtering a list of \"Archive::Tar::File\" objects\nbased on your criteria. For example, to extract only files that have\nthe 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\narchive. Consult the \"Archive::Tar::File\" documentation on how to\nuse these objects.\n\nHow do I access .tar.Z files?\nThe \"Archive::Tar\" module can optionally use \"Compress::Zlib\" (via\nthe \"IO::Zlib\" module) to access tar files that have been compressed\nwith \"gzip\". Unfortunately tar files compressed with the Unix\n\"compress\" utility cannot be read by \"Compress::Zlib\" and so cannot\nbe directly accesses by \"Archive::Tar\".\n\nIf the \"uncompress\" or \"gunzip\" programs are available, you can use\none of these workarounds to 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\nto 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\nwrites to disk. This is not a problem if you only deal with files\nand never look at their content or work solely with byte strings.\nBut if you use Unicode strings with character semantics, some\nadditional steps 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\nto disk via \"$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\ndisk, the \":utf8\" line discipline wasn't set by \"Archive::Tar\", so\nPerl tried to convert the string to ISO-8859 and failed. The written\nfile now contains garbage.\n\nFor this reason, Unicode strings need to be converted to\nUTF-8-encoded bytestrings before they are handed off to\n\"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\ntarball. Using \"getcontent()\" on the \"Archive::Tar::File\" object\nwill return its content as a bytestring, not as a Unicode string.\n\nIf you want it to be a Unicode string (because you want character\nsemantics with operations like regular expression matching), you\nneed to decode the UTF8-encoded content and have Perl convert it\ninto 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\n\"Archive::Tar\", because a tarball can contain many files, and each\nof 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.\nThis sometimes leads to warning 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\nlevels of AIX, all of which should be coming out in the 4th quarter of\n2009:\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:\n5765G0300 / AIX 5.3). It is possible to get an ifix for that problem. If\nyou need an ifix please contact your local IBM AIX 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.\nSuggestions welcome.\n\nAllow archives to be passed in as string\nCurrently, we only allow opened filehandles or filenames, but not\nstrings. The internals would need some reworking to facilitate\nstringified archives.\n\nFacilitate processing an opened filehandle of a compressed archive\nCurrently, we only support this if the filehandle is an IO::Zlib\nobject. Environments, like apache, will present you with an opened\nfilehandle to an uploaded file, which might be a compressed 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;\n\"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\nPOSIX-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\nAas, Rainer Tammer and especially Andrew Savige for their help and\nsuggestions.\n",
            "subsections": []
        },
        "COPYRIGHT": {
            "content": "This module is copyright (c) 2002 - 2009 Jos Boumans <kane@cpan.org>.\nAll rights reserved.\n\nThis library is free software; you may redistribute and/or modify it\nunder the same terms as Perl itself.\n",
            "subsections": []
        }
    },
    "summary": "Archive::Tar - module for manipulations of tar archives",
    "flags": [],
    "examples": [],
    "see_also": []
}