mingw/html/lib/PerlIO.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <ul>
  26
  27                 <li><a href="#custom_layers">Custom Layers</a></li>
  28                 <li><a href="#alternatives_to_raw">Alternatives to raw</a></li>
  29                 <li><a href="#defaults_and_how_to_override_them">Defaults and how to override them</a></li>
  30                 <li><a href="#querying_the_layers_of_filehandles">Querying the layers of filehandles</a></li>
  31         </ul>
  32
  33         <li><a href="#author">AUTHOR</a></li>
  34         <li><a href="#see_also">SEE ALSO</a></li>
  35 </ul>
  36 <!-- INDEX END -->
  37
  38 <hr />
  39 <p>
  40 </p>
  41 <h1><a name="name">NAME</a></h1>
  42 <p>PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space</p>
  43 <p>
  44 </p>
  45 <hr />
  46 <h1><a name="synopsis">SYNOPSIS</a></h1>
  47 <pre>
  48   open($fh,&quot;&lt;:crlf&quot;, &quot;my.txt&quot;); # support platform-native and CRLF text files</pre>
  49 <pre>
  50   open($fh,&quot;&lt;&quot;,&quot;his.jpg&quot;);      # portably open a binary file for reading
  51   binmode($fh);</pre>
  52 <pre>
  53   Shell:
  54     PERLIO=perlio perl ....</pre>
  55 <p>
  56 </p>
  57 <hr />
  58 <h1><a name="description">DESCRIPTION</a></h1>
  59 <p>When an undefined layer 'foo' is encountered in an <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_open"><code>open</code></a> or
  60 <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_binmode"><code>binmode</code></a> layer specification then C code performs the equivalent of:</p>
  61 <pre>
  62   use PerlIO 'foo';</pre>
  63 <p>The perl code in PerlIO.pm then attempts to locate a layer by doing</p>
  64 <pre>
  65   require PerlIO::foo;</pre>
  66 <p>Otherwise the <code>PerlIO</code> package is a place holder for additional
  67 PerlIO related functions.</p>
  68 <p>The following layers are currently defined:</p>
  69 <dl>
  70 <dt><strong><a name="item__3aunix">:unix</a></strong>
  71
  72 <dd>
  73 <p>Lowest level layer which provides basic PerlIO operations in terms of
  74 UNIX/POSIX numeric file descriptor calls
  75 (open(), read(), write(), lseek(), close()).</p>
  76 </dd>
  77 </li>
  78 <dt><strong><a name="item__3astdio">:stdio</a></strong>
  79
  80 <dd>
  81 <p>Layer which calls <code>fread</code>, <code>fwrite</code> and <code>fseek</code>/<code>ftell</code> etc.  Note
  82 that as this is ``real'' stdio it will ignore any layers beneath it and
  83 got straight to the operating system via the C library as usual.</p>
  84 </dd>
  85 </li>
  86 <dt><strong><a name="item__3aperlio">:perlio</a></strong>
  87
  88 <dd>
  89 <p>A from scratch implementation of buffering for PerlIO. Provides fast
  90 access to the buffer for <code>sv_gets</code> which implements perl's readline/&lt;&gt;
  91 and in general attempts to minimize data copying.</p>
  92 </dd>
  93 <dd>
  94 <p><a href="#item__3aperlio"><code>:perlio</code></a> will insert a <a href="#item__3aunix"><code>:unix</code></a> layer below itself to do low level IO.</p>
  95 </dd>
  96 </li>
  97 <dt><strong><a name="item__3acrlf">:crlf</a></strong>
  98
  99 <dd>
 100 <p>A layer that implements DOS/Windows like CRLF line endings.  On read
 101 converts pairs of CR,LF to a single ``\n'' newline character.  On write
 102 converts each ``\n'' to a CR,LF pair.  Note that this layer likes to be
 103 one of its kind: it silently ignores attempts to be pushed into the
 104 layer stack more than once.</p>
 105 </dd>
 106 <dd>
 107 <p>It currently does <em>not</em> mimic MS-DOS as far as treating of Control-Z
 108 as being an end-of-file marker.</p>
 109 </dd>
 110 <dd>
 111 <p>(Gory details follow) To be more exact what happens is this: after
 112 pushing itself to the stack, the <a href="#item__3acrlf"><code>:crlf</code></a> layer checks all the layers
 113 below itself to find the first layer that is capable of being a CRLF
 114 layer but is not yet enabled to be a CRLF layer.  If it finds such a
 115 layer, it enables the CRLFness of that other deeper layer, and then
 116 pops itself off the stack.  If not, fine, use the one we just pushed.</p>
 117 </dd>
 118 <dd>
 119 <p>The end result is that a <a href="#item__3acrlf"><code>:crlf</code></a> means ``please enable the first CRLF
 120 layer you can find, and if you can't find one, here would be a good
 121 spot to place a new one.''</p>
 122 </dd>
 123 <dd>
 124 <p>Based on the <a href="#item__3aperlio"><code>:perlio</code></a> layer.</p>
 125 </dd>
 126 </li>
 127 <dt><strong><a name="item__3ammap">:mmap</a></strong>
 128
 129 <dd>
 130 <p>A layer which implements ``reading'' of files by using <code>mmap()</code> to
 131 make (whole) file appear in the process's address space, and then
 132 using that as PerlIO's ``buffer''. This <em>may</em> be faster in certain
 133 circumstances for large files, and may result in less physical memory
 134 use when multiple processes are reading the same file.</p>
 135 </dd>
 136 <dd>
 137 <p>Files which are not <code>mmap()</code>-able revert to behaving like the <a href="#item__3aperlio"><code>:perlio</code></a>
 138 layer. Writes also behave like <a href="#item__3aperlio"><code>:perlio</code></a> layer as <code>mmap()</code> for write
 139 needs extra house-keeping (to extend the file) which negates any advantage.</p>
 140 </dd>
 141 <dd>
 142 <p>The <a href="#item__3ammap"><code>:mmap</code></a> layer will not exist if platform does not support <code>mmap()</code>.</p>
 143 </dd>
 144 </li>
 145 <dt><strong><a name="item__3autf8">:utf8</a></strong>
 146
 147 <dd>
 148 <p>Declares that the stream accepts perl's internal encoding of
 149 characters.  (Which really is UTF-8 on ASCII machines, but is
 150 UTF-EBCDIC on EBCDIC machines.)  This allows any character perl can
 151 represent to be read from or written to the stream. The UTF-X encoding
 152 is chosen to render simple text parts (i.e.  non-accented letters,
 153 digits and common punctuation) human readable in the encoded file.</p>
 154 </dd>
 155 <dd>
 156 <p>Here is how to write your native data out using UTF-8 (or UTF-EBCDIC)
 157 and then read it back in.</p>
 158 </dd>
 159 <dd>
 160 <pre>
 161         open(F, &quot;&gt;:utf8&quot;, &quot;data.utf&quot;);
 162         print F $out;
 163         close(F);</pre>
 164 </dd>
 165 <dd>
 166 <pre>
 167         open(F, &quot;&lt;:utf8&quot;, &quot;data.utf&quot;);
 168         $in = &lt;F&gt;;
 169         close(F);</pre>
 170 </dd>
 171 </li>
 172 <dt><strong><a name="item__3abytes">:bytes</a></strong>
 173
 174 <dd>
 175 <p>This is the inverse of <a href="#item__3autf8"><code>:utf8</code></a> layer. It turns off the flag
 176 on the layer below so that data read from it is considered to
 177 be ``octets'' i.e. characters in range 0..255 only. Likewise
 178 on output perl will warn if a ``wide'' character is written
 179 to a such a stream.</p>
 180 </dd>
 181 </li>
 182 <dt><strong><a name="item__3araw">:raw</a></strong>
 183
 184 <dd>
 185 <p>The <a href="#item__3araw"><code>:raw</code></a> layer is <em>defined</em> as being identical to calling
 186 <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_binmode"><code>binmode($fh)</code></a> - the stream is made suitable for passing binary data
 187 i.e. each byte is passed as-is. The stream will still be
 188 buffered.</p>
 189 </dd>
 190 <dd>
 191 <p>In Perl 5.6 and some books the <a href="#item__3araw"><code>:raw</code></a> layer (previously sometimes also
 192 referred to as a ``discipline'') is documented as the inverse of the
 193 <a href="#item__3acrlf"><code>:crlf</code></a> layer. That is no longer the case - other layers which would
 194 alter binary nature of the stream are also disabled.  If you want UNIX
 195 line endings on a platform that normally does CRLF translation, but still
 196 want UTF-8 or encoding defaults the appropriate thing to do is to add
 197 <a href="#item__3aperlio"><code>:perlio</code></a> to PERLIO environment variable.</p>
 198 </dd>
 199 <dd>
 200 <p>The implementation of <a href="#item__3araw"><code>:raw</code></a> is as a pseudo-layer which when ``pushed''
 201 pops itself and then any layers which do not declare themselves as suitable
 202 for binary data. (Undoing :utf8 and :crlf are implemented by clearing
 203 flags rather than popping layers but that is an implementation detail.)</p>
 204 </dd>
 205 <dd>
 206 <p>As a consequence of the fact that <a href="#item__3araw"><code>:raw</code></a> normally pops layers
 207 it usually only makes sense to have it as the only or first element in
 208 a layer specification.  When used as the first element it provides
 209 a known base on which to build e.g.</p>
 210 </dd>
 211 <dd>
 212 <pre>
 213     open($fh,&quot;:raw:utf8&quot;,...)</pre>
 214 </dd>
 215 <dd>
 216 <p>will construct a ``binary'' stream, but then enable UTF-8 translation.</p>
 217 </dd>
 218 </li>
 219 <dt><strong><a name="item__3apop">:pop</a></strong>
 220
 221 <dd>
 222 <p>A pseudo layer that removes the top-most layer. Gives perl code
 223 a way to manipulate the layer stack. Should be considered
 224 as experimental. Note that <a href="#item__3apop"><code>:pop</code></a> only works on real layers
 225 and will not undo the effects of pseudo layers like <a href="#item__3autf8"><code>:utf8</code></a>.
 226 An example of a possible use might be:</p>
 227 </dd>
 228 <dd>
 229 <pre>
 230     open($fh,...)
 231     ...
 232     binmode($fh,&quot;:encoding(...)&quot;);  # next chunk is encoded
 233     ...
 234     binmode($fh,&quot;:pop&quot;);            # back to un-encoded</pre>
 235 </dd>
 236 <dd>
 237 <p>A more elegant (and safer) interface is needed.</p>
 238 </dd>
 239 </li>
 240 <dt><strong><a name="item__3awin32">:win32</a></strong>
 241
 242 <dd>
 243 <p>On Win32 platforms this <em>experimental</em> layer uses native ``handle'' IO
 244 rather than unix-like numeric file descriptor layer. Known to be
 245 buggy as of perl 5.8.2.</p>
 246 </dd>
 247 </li>
 248 </dl>
 249 <p>
 250 </p>
 251 <h2><a name="custom_layers">Custom Layers</a></h2>
 252 <p>It is possible to write custom layers in addition to the above builtin
 253 ones, both in C/XS and Perl.  Two such layers (and one example written
 254 in Perl using the latter) come with the Perl distribution.</p>
 255 <dl>
 256 <dt><strong><a name="item__3aencoding">:encoding</a></strong>
 257
 258 <dd>
 259 <p>Use <code>:encoding(ENCODING)</code> either in <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_open"><code>open()</code></a> or <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_binmode"><code>binmode()</code></a> to install
 260 a layer that does transparently character set and encoding transformations,
 261 for example from Shift-JIS to Unicode.  Note that under <code>stdio</code>
 262 an <a href="#item__3aencoding"><code>:encoding</code></a> also enables <a href="#item__3autf8"><code>:utf8</code></a>.  See <a href="file://C|\msysgit\mingw\html/lib/PerlIO/encoding.html">the PerlIO::encoding manpage</a>
 263 for more information.</p>
 264 </dd>
 265 </li>
 266 <dt><strong><a name="item__3avia">:via</a></strong>
 267
 268 <dd>
 269 <p>Use <code>:via(MODULE)</code> either in <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_open"><code>open()</code></a> or <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_binmode"><code>binmode()</code></a> to install a layer
 270 that does whatever transformation (for example compression /
 271 decompression, encryption / decryption) to the filehandle.
 272 See <a href="file://C|\msysgit\mingw\html/lib/PerlIO/via.html">the PerlIO::via manpage</a> for more information.</p>
 273 </dd>
 274 </li>
 275 </dl>
 276 <p>
 277 </p>
 278 <h2><a name="alternatives_to_raw">Alternatives to raw</a></h2>
 279 <p>To get a binary stream an alternate method is to use:</p>
 280 <pre>
 281     open($fh,&quot;whatever&quot;)
 282     binmode($fh);</pre>
 283 <p>this has advantage of being backward compatible with how such things have
 284 had to be coded on some platforms for years.</p>
 285 <p>To get an un-buffered stream specify an unbuffered layer (e.g. <a href="#item__3aunix"><code>:unix</code></a>)
 286 in the open call:</p>
 287 <pre>
 288     open($fh,&quot;&lt;:unix&quot;,$path)</pre>
 289 <p>
 290 </p>
 291 <h2><a name="defaults_and_how_to_override_them">Defaults and how to override them</a></h2>
 292 <p>If the platform is MS-DOS like and normally does CRLF to ``\n''
 293 translation for text files then the default layers are :</p>
 294 <pre>
 295   unix crlf</pre>
 296 <p>(The low level ``unix'' layer may be replaced by a platform specific low
 297 level layer.)</p>
 298 <p>Otherwise if <code>Configure</code> found out how to do ``fast'' IO using system's
 299 stdio, then the default layers are:</p>
 300 <pre>
 301   unix stdio</pre>
 302 <p>Otherwise the default layers are</p>
 303 <pre>
 304   unix perlio</pre>
 305 <p>These defaults may change once perlio has been better tested and tuned.</p>
 306 <p>The default can be overridden by setting the environment variable
 307 PERLIO to a space separated list of layers (<code>unix</code> or platform low
 308 level layer is always pushed first).</p>
 309 <p>This can be used to see the effect of/bugs in the various layers e.g.</p>
 310 <pre>
 311   cd .../perl/t
 312   PERLIO=stdio  ./perl harness
 313   PERLIO=perlio ./perl harness</pre>
 314 <p>For the various value of PERLIO see <a href="file://C|\msysgit\mingw\html/pod/perlrun.html#perlio">PERLIO in the perlrun manpage</a>.</p>
 315 <p>
 316 </p>
 317 <h2><a name="querying_the_layers_of_filehandles">Querying the layers of filehandles</a></h2>
 318 <p>The following returns the <strong>names</strong> of the PerlIO layers on a filehandle.</p>
 319 <pre>
 320    my @layers = PerlIO::get_layers($fh); # Or FH, *FH, &quot;FH&quot;.</pre>
 321 <p>The layers are returned in the order an <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_open"><code>open()</code></a> or <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_binmode"><code>binmode()</code></a> call would
 322 use them.  Note that the ``default stack'' depends on the operating
 323 system and on the Perl version, and both the compile-time and
 324 runtime configurations of Perl.</p>
 325 <p>The following table summarizes the default layers on UNIX-like and
 326 DOS-like platforms and depending on the setting of the <code>$ENV{PERLIO}</code>:</p>
 327 <pre>
 328  PERLIO     UNIX-like                   DOS-like
 329  ------     ---------                   --------
 330  unset / &quot;&quot; unix perlio / stdio [1]     unix crlf
 331  stdio      unix perlio / stdio [1]     stdio
 332  perlio     unix perlio                 unix perlio
 333  mmap       unix mmap                   unix mmap</pre>
 334 <pre>
 335  # [1] &quot;stdio&quot; if Configure found out how to do &quot;fast stdio&quot; (depends
 336  # on the stdio implementation) and in Perl 5.8, otherwise &quot;unix perlio&quot;</pre>
 337 <p>By default the layers from the input side of the filehandle is
 338 returned, to get the output side use the optional <code>output</code> argument:</p>
 339 <pre>
 340    my @layers = PerlIO::get_layers($fh, output =&gt; 1);</pre>
 341 <p>(Usually the layers are identical on either side of a filehandle but
 342 for example with sockets there may be differences, or if you have
 343 been using the <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_open"><code>open</code></a> pragma.)</p>
 344 <p>There is no set_layers(), nor does <code>get_layers()</code> return a tied array
 345 mirroring the stack, or anything fancy like that.  This is not
 346 accidental or unintentional.  The PerlIO layer stack is a bit more
 347 complicated than just a stack (see for example the behaviour of <a href="#item__3araw"><code>:raw</code></a>).
 348 You are supposed to use <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_open"><code>open()</code></a> and <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_binmode"><code>binmode()</code></a> to manipulate the stack.</p>
 349 <p><strong>Implementation details follow, please close your eyes.</strong></p>
 350 <p>The arguments to layers are by default returned in parenthesis after
 351 the name of the layer, and certain layers (like <code>utf8</code>) are not real
 352 layers but instead flags on real layers: to get all of these returned
 353 separately use the optional <code>details</code> argument:</p>
 354 <pre>
 355    my @layer_and_args_and_flags = PerlIO::get_layers($fh, details =&gt; 1);</pre>
 356 <p>The result will be up to be three times the number of layers:
 357 the first element will be a name, the second element the arguments
 358 (unspecified arguments will be <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a>), the third element the flags,
 359 the fourth element a name again, and so forth.</p>
 360 <p><strong>You may open your eyes now.</strong></p>
 361 <p>
 362 </p>
 363 <hr />
 364 <h1><a name="author">AUTHOR</a></h1>
 365 <p>Nick Ing-Simmons &lt;<a href="mailto:nick@ing-simmons.net">nick@ing-simmons.net</a>&gt;</p>
 366 <p>
 367 </p>
 368 <hr />
 369 <h1><a name="see_also">SEE ALSO</a></h1>
 370 <p><a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_binmode">binmode in the perlfunc manpage</a>, <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_open">open in the perlfunc manpage</a>, <a href="file://C|\msysgit\mingw\html/pod/perlunicode.html">the perlunicode manpage</a>, <a href="file://C|\msysgit\mingw\html/pod/perliol.html">the perliol manpage</a>,
 371 <a href="file://C|\msysgit\mingw\html/lib/Encode.html">the Encode manpage</a></p>
 372 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 373 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 374 <big><strong><span class="block">&nbsp;PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space</span></strong></big>
 375 </td></tr>
 376 </table>
 377
 378 </body>
 379
 380 </html>