{
    "mode": "perldoc",
    "parameter": "PerlIO::via",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/PerlIO%3A%3Avia/json",
    "generated": "2026-06-13T21:29:27Z",
    "synopsis": "use PerlIO::via::Layer;\nopen($fh,\"<:via(Layer)\",...);\nuse Some::Other::Package;\nopen($fh,\">:via(Some::Other::Package)\",...);",
    "sections": {
        "NAME": {
            "content": "PerlIO::via - Helper class for PerlIO layers implemented in perl\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use PerlIO::via::Layer;\nopen($fh,\"<:via(Layer)\",...);\n\nuse Some::Other::Package;\nopen($fh,\">:via(Some::Other::Package)\",...);\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "The PerlIO::via module allows you to develop PerlIO layers in Perl, without having to go into\nthe nitty gritty of programming C with XS as the interface to Perl.\n\nOne example module, PerlIO::via::QuotedPrint, is included with Perl 5.8.0, and more example\nmodules are available from CPAN, such as PerlIO::via::StripHTML and PerlIO::via::Base64. The\nPerlIO::via::StripHTML module for instance, allows you to say:\n\nuse PerlIO::via::StripHTML;\nopen( my $fh, \"<:via(StripHTML)\", \"index.html\" );\nmy @line = <$fh>;\n\nto obtain the text of an HTML-file in an array with all the HTML-tags automagically removed.\n\nPlease note that if the layer is created in the PerlIO::via:: namespace, it does not have to be\nfully qualified. The PerlIO::via module will prefix the PerlIO::via:: namespace if the specified\nmodulename does not exist as a fully qualified module name.\n",
            "subsections": []
        },
        "EXPECTED METHODS": {
            "content": "To create a Perl module that implements a PerlIO layer in Perl (as opposed to in C using XS as\nthe interface to Perl), you need to supply some of the following subroutines. It is recommended\nto create these Perl modules in the PerlIO::via:: namespace, so that they can easily be located\non CPAN and use the default namespace feature of the PerlIO::via module itself.\n\nPlease note that this is an area of recent development in Perl and that the interface described\nhere is therefore still subject to change (and hopefully will have better documentation and more\nexamples).\n\nIn the method descriptions below *$fh* will be a reference to a glob which can be treated as a\nperl file handle. It refers to the layer below. *$fh* is not passed if the layer is at the\nbottom of the stack, for this reason and to maintain some level of \"compatibility\" with\nTIEHANDLE classes it is passed last.\n\n$class->PUSHED([$mode,[$fh]])\nShould return an object or the class, or -1 on failure. (Compare TIEHANDLE.) The arguments\nare an optional mode string (\"r\", \"w\", \"w+\", ...) and a filehandle for the PerlIO layer\nbelow. Mandatory.\n\nWhen the layer is pushed as part of an \"open\" call, \"PUSHED\" will be called *before* the\nactual open occurs, whether that be via \"OPEN\", \"SYSOPEN\", \"FDOPEN\" or by letting a lower\nlayer do the open.\n\n$obj->POPPED([$fh])\nOptional - called when the layer is about to be removed.\n\n$obj->UTF8($belowFlag,[$fh])\nOptional - if present it will be called immediately after PUSHED has returned. It should\nreturn a true value if the layer expects data to be UTF-8 encoded. If it returns true, the\nresult is as if the caller had done\n\n\":via(YourClass):utf8\"\n\nIf not present or if it returns false, then the stream is left with the UTF-8 flag clear.\nThe *$belowFlag* argument will be true if there is a layer below and that layer was\nexpecting UTF-8.\n\n$obj->OPEN($path,$mode,[$fh])\nOptional - if not present a lower layer does the open. If present, called for normal opens\nafter the layer is pushed. This function is subject to change as there is no easy way to get\na lower layer to do the open and then regain control.\n\n$obj->BINMODE([$fh])\nOptional - if not present the layer is popped on binmode($fh) or when \":raw\" is pushed. If\npresent it should return 0 on success, -1 on error, or undef to pop the layer.\n\n$obj->FDOPEN($fd,[$fh])\nOptional - if not present a lower layer does the open. If present, called after the layer is\npushed for opens which pass a numeric file descriptor. This function is subject to change as\nthere is no easy way to get a lower layer to do the open and then regain control.\n\n$obj->SYSOPEN($path,$imode,$perm,[$fh])\nOptional - if not present a lower layer does the open. If present, called after the layer is\npushed for sysopen style opens which pass a numeric mode and permissions. This function is\nsubject to change as there is no easy way to get a lower layer to do the open and then\nregain control.\n\n$obj->FILENO($fh)\nReturns a numeric value for a Unix-like file descriptor. Returns -1 if there isn't one.\nOptional. Default is fileno($fh).\n\n$obj->READ($buffer,$len,$fh)\nReturns the number of octets placed in $buffer (must be less than or equal to $len).\nOptional. Default is to use FILL instead.\n\n$obj->WRITE($buffer,$fh)\nReturns the number of octets from $buffer that have been successfully written.\n\n$obj->FILL($fh)\nShould return a string to be placed in the buffer. Optional. If not provided, must provide\nREAD or reject handles open for reading in PUSHED.\n\n$obj->CLOSE($fh)\nShould return 0 on success, -1 on error. Optional.\n\n$obj->SEEK($posn,$whence,$fh)\nShould return 0 on success, -1 on error. Optional. Default is to fail, but that is likely to\nbe changed in future.\n\n$obj->TELL($fh)\nReturns file position. Optional. Default to be determined.\n\n$obj->UNREAD($buffer,$fh)\nReturns the number of octets from $buffer that have been successfully saved to be returned\non future FILL/READ calls. Optional. Default is to push data into a temporary layer above\nthis one.\n\n$obj->FLUSH($fh)\nFlush any buffered write data. May possibly be called on readable handles too. Should return\n0 on success, -1 on error.\n\n$obj->SETLINEBUF($fh)\nOptional. No return.\n\n$obj->CLEARERR($fh)\nOptional. No return.\n\n$obj->ERROR($fh)\nOptional. Returns error state. Default is no error until a mechanism to signal error (die?)\nis worked out.\n\n$obj->EOF($fh)\nOptional. Returns end-of-file state. Default is a function of the return value of FILL or\nREAD.\n",
            "subsections": []
        },
        "EXAMPLES": {
            "content": "Check the PerlIO::via:: namespace on CPAN for examples of PerlIO layers implemented in Perl. To\ngive you an idea how simple the implementation of a PerlIO layer can look, a simple example is\nincluded here.\n",
            "subsections": [
                {
                    "name": "Example - a Hexadecimal Handle",
                    "content": "Given the following module, PerlIO::via::Hex :\n\npackage PerlIO::via::Hex;\n\nsub PUSHED\n{\nmy ($class,$mode,$fh) = @;\n# When writing we buffer the data\nmy $buf = '';\nreturn bless \\$buf,$class;\n}\n\nsub FILL\n{\nmy ($obj,$fh) = @;\nmy $line = <$fh>;\nreturn (defined $line) ? pack(\"H*\", $line) : undef;\n}\n\nsub WRITE\n{\nmy ($obj,$buf,$fh) = @;\n$$obj .= unpack(\"H*\", $buf);\nreturn length($buf);\n}\n\nsub FLUSH\n{\nmy ($obj,$fh) = @;\nprint $fh $$obj or return -1;\n$$obj = '';\nreturn 0;\n}\n\n1;\n\nThe following code opens up an output handle that will convert any output to a hexadecimal dump\nof the output bytes: for example \"A\" will be converted to \"41\" (on ASCII-based machines, on\nEBCDIC platforms the \"A\" will become \"c1\")\n\nuse PerlIO::via::Hex;\nopen(my $fh, \">:via(Hex)\", \"foo.hex\");\n\nand the following code will read the hexdump in and convert it on the fly back into bytes:\n\nopen(my $fh, \"<:via(Hex)\", \"foo.hex\");\n"
                }
            ]
        }
    },
    "summary": "PerlIO::via - Helper class for PerlIO layers implemented in perl",
    "flags": [],
    "examples": [
        "Check the PerlIO::via:: namespace on CPAN for examples of PerlIO layers implemented in Perl. To",
        "give you an idea how simple the implementation of a PerlIO layer can look, a simple example is",
        "included here.",
        "Given the following module, PerlIO::via::Hex :",
        "package PerlIO::via::Hex;",
        "sub PUSHED",
        "my ($class,$mode,$fh) = @;",
        "# When writing we buffer the data",
        "my $buf = '';",
        "return bless \\$buf,$class;",
        "sub FILL",
        "my ($obj,$fh) = @;",
        "my $line = <$fh>;",
        "return (defined $line) ? pack(\"H*\", $line) : undef;",
        "sub WRITE",
        "my ($obj,$buf,$fh) = @;",
        "$$obj .= unpack(\"H*\", $buf);",
        "return length($buf);",
        "sub FLUSH",
        "my ($obj,$fh) = @;",
        "print $fh $$obj or return -1;",
        "$$obj = '';",
        "return 0;",
        "1;",
        "The following code opens up an output handle that will convert any output to a hexadecimal dump",
        "of the output bytes: for example \"A\" will be converted to \"41\" (on ASCII-based machines, on",
        "EBCDIC platforms the \"A\" will become \"c1\")",
        "use PerlIO::via::Hex;",
        "open(my $fh, \">:via(Hex)\", \"foo.hex\");",
        "and the following code will read the hexdump in and convert it on the fly back into bytes:",
        "open(my $fh, \"<:via(Hex)\", \"foo.hex\");"
    ],
    "see_also": []
}