PerlIO::Layers(3pm)

📦
version 0.012 · 9 versions
, in ubuntu stonking

💖 PerlIO::Layers 💖

okay bestie, listen — this is PerlIO::Layers, straight out of the User Contributed Perl Documentation, and it's literally your filehandle's vibe check. it tells you what your filehandle can actually do. no cap. 🦋

✨ VERSION ✨

version 0.012 — yes she's a real one 💅

🌸 SYNOPSIS 🌸

like, here's the whole thing in action:

use PerlIO::Layers qw/query_handle/;

if (!query_handle(\*STDOUT, 'binary')) {
    ...
}

see how easy that was? iconic. 👑

💜 DESCRIPTION 💜

so here's the tea: Perl's filehandles aren't just, like, one thing. they're a whole stack of layers, bestie. the bottom-most one is usually doing the actual IO (the heavy lifting, main character energy), and the ones stacked on top are doing buffering, encoding/decoding, or transformations. and PerlIO::Layers lets you query the filehandle's properties about all these layers. it's giving detective. it's giving nosy best friend. 🔍

🎀 FUNCTIONS 🎀

🌈 query_handle($fh, $query_name [, $argument]) 🌈

this one queries a filehandle for some information. and get this — all the queries can take an optional argument, and if you pass it, it'll test for that layer's properties instead of checking every single layer of the handle. so flexible. so versatile. 🙈

currently supported queries include:

  • layer — checks if a certain layer is present. heads up though: unlike basically every other property, $argument is mandatory for this one. you have to give it. fr fr.
  • utf8 — checks whether the filehandle/layer handles unicode ✨
  • crlf — checks whether the filehandle/layer does crlf translation
  • binary — checks whether the filehandle/layer is binary. and ngl, this test is pessimistic — for unknown layers it'll just assume it's not binary. it's a hater like that 😭
  • mappable — checks whether the filehandle/layer is memory mappable. it's the same as binary, EXCEPT the "utf8" layer is accepted. so like, binary but with one (1) exception 💫
  • buffered — checks whether the filehandle/layer is buffered.
  • readable — checks whether the filehandle/layer is readable.
  • writeable — checks whether the filehandle/layer is writeable.
  • open — checks whether the filehandle/layer is open.
  • temp — checks whether the filehandle/layer refers to a temporary file.
  • can_crlf — checks whether layer $argument (or any layer, if $argument isn't given) can do crlf translation.
  • line_buffered — checks whether the filehandle is in line-buffering mode.
  • autoflush — checks whether the filehandle is in unbuffering mode. and okay, important note: this is not the opposite of buffering, it's more similar to autoflush — hence the name of this test. so don't come for me. 🫶
  • buffer_size — checks whether the buffer size is equal to $argument.

🦋 get_layers($fh) 🦋

gets you all the info on the layers of a filehandle. it returns a list, and each entry has 3 elements:

  1. the name of the layer
  2. the arguments of the layer (may be undef)
  3. an arrayref with the flags of the layer as strings

and the flags array can contain any of these values:

  • EOF — end of file has been reached. that's it, that's the flag. 🥲
  • CANWRITE — writes are permitted, i.e. opened as ">" or "+<" or ">>", etc.
  • CANREAD — reads are permitted i.e. opened "<" or "+>".
  • ERROR — an error has occurred. 💀
  • TRUNCATE — truncate file suggested by open mode.
  • APPEND — all writes should be appends.
  • CRLF — layer is performing Win32-like "\n" mapped to CR,LF for output and CR,LF mapped to "\n" for input. normally the provided "crlf" layer is the only layer that need bother about this. "binmode" will mess with this flag rather than add/remove layers if the PERLIO_K_CANCRLF bit is set for the layers class.
  • UTF8 — data written to this layer should be UTF-8 encoded; data provided by this layer should be considered UTF-8 encoded. can be set on any layer by the ":utf8" dummy layer. also set on the ":encoding" layer.
  • UNBUF — layer is unbuffered — i.e. write to next layer down should occur for each write to this layer.
  • WRBUF — the buffer for this layer currently holds data written to it but not sent to next layer.
  • RDBUF — the buffer for this layer currently holds unconsumed data read from layer below.
  • LINEBUF — layer is line buffered. write data should be passed to next layer down whenever a "\n" is seen. any data beyond the "\n" should then be processed.
  • TEMP — file has been unlink()ed, or should be deleted on close().
  • OPEN — handle is open.
  • FASTGETS — this instance of this layer supports the "fast gets" interface. normally set based on PERLIO_K_FASTGETS for the class and by the existence of the function(s) in the table. however a class that normally provides that interface may need to avoid it on a particular instance. the "pending" layer needs to do this when it is pushed above a layer which does not support the interface.

and real talk: "query_handle" provides a more high level interface to all of this, so you should probably use that when you can. bestie advice. 💅

🌸 get_buffer_sizes($fh) 🌸

returns a list of buffer sizes for all buffered layers. unbuffered layers? skipped. not invited to the party. 🙅♀️

👑 AUTHOR 👑

Leon Timmermans <fawaka@gmail.com>

this software is copyright (c) 2010 by Leon Timmermans.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

okay that's the whole page, we ate and left no crumbs 🍓

signing off with the receipts: this was perl v5.42.3, dated 2026-08-19, and it's the PerlIO::Layers(3pm) page from the User Contributed Perl Documentation. go query a filehandle for me, bestie. mwah 💋✨🦋

📦 where this page comes from