Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PerlIO::Layers(3)     User Contributed Perl Documentation    PerlIO::Layers(3)

       PerlIO::Layers -	Querying your filehandle's capabilities

       version 0.012

	use PerlIO::Layers qw/query_handle/;

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

       Perl's filehandles are implemented as a stack of	layers,	with the
       bottom-most usually doing the actual IO and the higher ones doing
       buffering, encoding/decoding or transformations.	PerlIO::Layers allows
       you to query the	filehandle's properties	concerning these layers.

   query_handle($fh, $query_name [, $argument])
       This query a filehandle for some	information. All queries can take an
       optional	argument, that will test for that layer's properties instead
       of all layers of	the handle. Currently supported	queries	include:

       o   layer

	   Check the presence of a certain layer. Unlike most other properties
	   $argument is	mandatory for this query.

       o   utf8

	   Check whether the filehandle/layer handles unicode

       o   crlf

	   Check whether the filehandle/layer does crlf	translation

       o   binary

	   Check whether the filehandle/layer is binary. This test is
	   pessimistic (for unknown layers it will assume it's not binary).

       o   mappable

	   Checks whether the filehandle/layer is memory mappable. It is the
	   same	as binary, except that the "utf8" layer	is accepted.

       o   buffered

	   Check whether the filehandle/layer is buffered.

       o   readable

	   Check whether the filehandle/layer is readable.

       o   writeable

	   Check whether the filehandle/layer is writeable.

       o   open

	   Check whether the filehandle/layer is open.

       o   temp

	   Check whether the filehandle/layer refers to	a temporary file.

       o   can_crlf

	   Checks whether layer	$argument (or any layer	if $argument it	not
	   given) can do crlf translation.

       o   line_buffered

	   Check whether the filehandle	is in line-buffering mode.

       o   autoflush

	   Checks whether the filehandle is in unbuffering mode. Note that
	   this	is not the opposite of buffering, but more similar to
	   autoflush, hence the	name of	this test.

       o   buffer_size

	   Check whether the buffer size is equal to $argument.

       Gets information	on the layers of a filehandle. It's a list with	whose
       entries have 3 elements:	the name of the	layer, the arguments of	the
       layer (may be undef) and	an arrayref with the flags of the layer	as
       strings.	The flags array	can contain any	of these values:

       o   EOF

	   End of file has been	reached.

       o   CANWRITE

	   Writes are permitted, i.e. opened as	">" or "+<" or ">>", etc.

       o   CANREAD

	   Reads are permitted i.e. opened "<" or "+>".

       o   ERROR

	   An error has	occurred.

       o   TRUNCATE

	   Truncate file suggested by open mode.

       o   APPEND

	   All writes should be	appends.

       o   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.

       o   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 ":utf8" dummy layer. Also set on ":encoding" layer.

       o   UNBUF

	   Layer is unbuffered - i.e. write to next layer down should occur
	   for each write to this layer.

       o   WRBUF

	   The buffer for this layer currently holds data written to it	but
	   not sent to next layer.

       o   RDBUF

	   The buffer for this layer currently holds unconsumed	data read from
	   layer below.

       o   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.

       o   TEMP

	   File	has been unlink()ed, or	should be deleted on close().

       o   OPEN

	   Handle is open.

       o   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.

       "query_handle" provides a more high level interface to this, you	should
       probably	use that when you can.

       Returns a list of buffer	sizes for all buffered layers. Unbuffered
       layers are skipped.

       Leon Timmermans <>

       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.

perl v5.32.1			  2021-11-04		     PerlIO::Layers(3)


Want to link to this manual page? Use this URL:

home | help