{
    "mode": "perldoc",
    "parameter": "Dpkg::Compression::FileHandle",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Dpkg%3A%3ACompression%3A%3AFileHandle/json",
    "generated": "2026-06-13T04:18:15Z",
    "synopsis": "use Dpkg::Compression::FileHandle;\nmy ($fh, @lines);\n$fh = Dpkg::Compression::FileHandle->new(filename => 'sample.gz');\nprint $fh \"Something\\n\";\nclose $fh;\n$fh = Dpkg::Compression::FileHandle->new();\nopen($fh, '>', 'sample.bz2');\nprint $fh \"Something\\n\";\nclose $fh;\n$fh = Dpkg::Compression::FileHandle->new();\n$fh->open('sample.xz', 'w');\n$fh->print(\"Something\\n\");\n$fh->close();\n$fh = Dpkg::Compression::FileHandle->new(filename => 'sample.gz');\n@lines = <$fh>;\nclose $fh;\n$fh = Dpkg::Compression::FileHandle->new();\nopen($fh, '<', 'sample.bz2');\n@lines = <$fh>;\nclose $fh;\n$fh = Dpkg::Compression::FileHandle->new();\n$fh->open('sample.xz', 'r');\n@lines = $fh->getlines();\n$fh->close();",
    "sections": {
        "NAME": {
            "content": "Dpkg::Compression::FileHandle - class dealing transparently with file compression\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use Dpkg::Compression::FileHandle;\n\nmy ($fh, @lines);\n\n$fh = Dpkg::Compression::FileHandle->new(filename => 'sample.gz');\nprint $fh \"Something\\n\";\nclose $fh;\n\n$fh = Dpkg::Compression::FileHandle->new();\nopen($fh, '>', 'sample.bz2');\nprint $fh \"Something\\n\";\nclose $fh;\n\n$fh = Dpkg::Compression::FileHandle->new();\n$fh->open('sample.xz', 'w');\n$fh->print(\"Something\\n\");\n$fh->close();\n\n$fh = Dpkg::Compression::FileHandle->new(filename => 'sample.gz');\n@lines = <$fh>;\nclose $fh;\n\n$fh = Dpkg::Compression::FileHandle->new();\nopen($fh, '<', 'sample.bz2');\n@lines = <$fh>;\nclose $fh;\n\n$fh = Dpkg::Compression::FileHandle->new();\n$fh->open('sample.xz', 'r');\n@lines = $fh->getlines();\n$fh->close();\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Dpkg::Compression::FileHandle is a class that can be used like any filehandle and that deals\ntransparently with compressed files. By default, the compression scheme is guessed from the\nfilename but you can override this behaviour with the method \"setcompression\".\n\nIf you don't open the file explicitly, it will be auto-opened on the first read or write\noperation based on the filename set at creation time (or later with the \"setfilename\" method).\n\nOnce a file has been opened, the filehandle must be closed before being able to open another\nfile.\n",
            "subsections": []
        },
        "STANDARD FUNCTIONS": {
            "content": "The standard functions acting on filehandles should accept a Dpkg::Compression::FileHandle\nobject transparently including \"open\" (only when using the variant with 3 parameters), \"close\",\n\"binmode\", \"eof\", \"fileno\", \"getc\", \"print\", \"printf\", \"read\", \"sysread\", \"say\", \"write\",\n\"syswrite\", \"seek\", \"sysseek\", \"tell\".\n\nNote however that \"seek\" and \"sysseek\" will only work on uncompressed files as compressed files\nare really pipes to the compressor programs and you can't seek on a pipe.\n",
            "subsections": []
        },
        "FileHandle METHODS": {
            "content": "The class inherits from IO::File so all methods that work on this class should work for\nDpkg::Compression::FileHandle too. There may be exceptions though.\n",
            "subsections": []
        },
        "PUBLIC METHODS": {
            "content": "$fh = Dpkg::Compression::FileHandle->new(%opts)\nCreates a new filehandle supporting on-the-fly compression/decompression. Supported options\nare \"filename\", \"compression\", \"compressionlevel\" (see respective set* functions) and\n\"addcompext\". If \"addcompext\" evaluates to true, then the extension corresponding to the\nselected compression scheme is automatically added to the recorded filename. It's obviously\nincompatible with automatic detection of the compression method.\n\n$fh->ensureopen($mode, %opts)\nEnsure the file is opened in the requested mode (\"r\" for read and \"w\" for write). The\noptions are passed down to the compressor's spawn() call, if one is used. Opens the file\nwith the recorded filename if needed. If the file is already open but not in the requested\nmode, then it errors out.\n\n$fh->setcompression($comp)\nDefines the compression method used. $comp should one of the methods supported by\nDpkg::Compression or \"none\" or \"auto\". \"none\" indicates that the file is uncompressed and\n\"auto\" indicates that the method must be guessed based on the filename extension used.\n\n$fh->setcompressionlevel($level)\nIndicate the desired compression level. It should be a value accepted by the function\n\"compressionisvalidlevel\" of Dpkg::Compression.\n\n$fh->setfilename($name, [$addcompext])\nUse $name as filename when the file must be opened/created. If $addcompext is passed, it\nindicates whether the default extension of the compression method must be automatically\nadded to the filename (or not).\n\n$file = $fh->getfilename()\nReturns the filename that would be used when the filehandle must be opened (both in read and\nwrite mode). This function errors out if \"addcompext\" is enabled while the compression\nmethod is set to \"auto\". The returned filename includes the extension of the compression\nmethod if \"addcompext\" is enabled.\n\n$ret = $fh->usecompression()\nReturns \"0\" if no compression is used and the compression method used otherwise. If the\ncompression is set to \"auto\", the value returned depends on the extension of the filename\nobtained with the getfilename method.\n\n$realfh = $fh->getfilehandle()\nReturns the real underlying filehandle. Useful if you want to pass it along in a derived\nclass.\n",
            "subsections": []
        },
        "DERIVED CLASSES": {
            "content": "If you want to create a class that inherits from Dpkg::Compression::FileHandle you must be aware\nthat the object is a reference to a GLOB that is returned by Symbol::gensym() and as such it's\nnot a HASH.\n\nYou can store internal data in a hash but you have to use \"*$self-\"{...}> to access the\nassociated hash like in the example below:\n\nsub setoption {\nmy ($self, $value) = @;\n*$self->{option} = $value;\n}\n",
            "subsections": []
        },
        "CHANGES": {
            "content": "Version 1.01 (dpkg 1.17.11)\nNew argument: $fh->ensureopen() accepts an %opts argument.\n\nVersion 1.00 (dpkg 1.15.6)\nMark the module as public.\n",
            "subsections": []
        }
    },
    "summary": "Dpkg::Compression::FileHandle - class dealing transparently with file compression",
    "flags": [],
    "examples": [],
    "see_also": []
}