Module:...File::IO(3)

📦 version 1.1.3, in alpine 3.24

💖 NAME 💖

bestie, you're on the Module:...File::IO(3) page from User Contributed Perl Documentation, and the module is Module::Generic::File::IO — File IO Object Wrapper. It's giving filehandle wrapper realness, no cap. 🎀

✨ SYNOPSIS ✨

use Module::Generic::File::IO;
my $io = Module::Generic::File::IO->new ||
    die( Module::Generic::File::IO->error );

my $io = Module::Generic::File::IO->new( 'file.txt', '>' ) ||
    die( Module::Generic::File::IO->error );

my $io = Module::Generic::File::IO->new( fileno => $fileno ) ||
    die( Module::Generic::File::IO->error );

use Module::Generic::File::IO qw( wraphandle );
my $io = wraphandle( $fh );
my $io = wraphandle( $fh, '>' );

🌸 VERSION 🌸

v0.2.0 — short, sweet, iconic. 🦋

💅 DESCRIPTION 💅

Okay so this is a thin wrapper that inherits from IO::File, and its whole thing is providing a uniform api in conformity with standard api call throughout the Module::Generic modules family. It also makes sure that a call to any IO::File will never die — instead it sets an error and returns undef in scalar context or an empty list in list context. Periodt.

Supported methods are rigorously the same as IO::File and IO::Handle on top of all the standard ones from Module::Generic.

The IO methods are listed below for convenience, but bestie, make sure to check the IO::File documentation for more information. 💖

🛠️ CONSTRUCTOR 🛠️

new

This instantiates a new Module::Generic::File::IO object and returns it. ✨

It optionally takes the following parameters:

  • fileno — a file descriptor. When this is provided, the newly created object will perform a fdopen on the file descriptor provided.
  • mode — a mode which will be used along with fileno to fdopen the file descriptor. Possible values can be "<", "+<", ">+", "+>", etc and "r", "r+", "w", "w+". "a" and "a+".

See IO::File, and "open" in perlfunc for more information.

🧚 FUNCTIONS 🧚

wraphandle

my $io = Module::Generic::File::IO::wraphandle( $fh, '>' );
# or
use Module::Generic::File::IO qw( wraphandle );
my $io = wraphandle( $fh, '>' );

Provided with a filehandle and an optional mode, this returns a newly created Module::Generic::File::IO. 🫶

By default, the mode will be '<'.

👑 METHODS 👑

  • args — returns an array reference containing the original arguments passed during object instantiation.
  • autoflush — see "autoflush" in IO::Handle for details.
  • binmode — see "binmode" in IO::File for details.
  • blocking — see "blocking" in IO::Handle for details.
  • can_read — returns true if one can read from this filehandle, or false otherwise.
  • can_write — returns true if one can write from this filehandle, or false otherwise.
  • close — see "close" in IO::Handle for details.
  • eof — see "eof" in IO::Handle for details.
  • fcntl — see "fcntl" in IO::Handle for details.
  • fdopen — see "fdopen" in IO::Handle for details.
  • fileno — see "fileno" in IO::Handle for details.
  • flags — returns the filehandle flags value using "fcntl" in perlfunc.
  • flock — returns the filehandle flock using "flock" in perlfunc.
  • flush — see "flush" in IO::Handle for details.
  • format_formfeed — see "format_formfeed" in IO::Handle for details.
  • format_line_break_characters — see "format_line_break_characters" in IO::Handle for details.
  • format_lines_left — see "format_lines_left" in IO::Handle for details.
  • format_lines_per_page — see "format_lines_per_page" in IO::Handle for details.
  • format_name — see "format_name" in IO::Handle for details.
  • format_page_number — see "format_page_number" in IO::Handle for details.
  • format_top_name — see "format_top_name" in IO::Handle for details.
  • format_write — see "format_write" in IO::Handle for details.
  • formline — see "formline" in IO::Handle for details.
  • getc — see "getc" in IO::Handle for details.
  • getline — see "getline" in IO::Handle for details.
  • getlines — see "getlines" in IO::Handle for details.
  • getpos — see "getpos" in IO::Seekable for details.
  • input_line_number — see "input_line_number" in IO::Handle for details.
  • input_record_separator — see "input_record_separator" in IO::Handle for details.
  • ioctl — see "ioctl" in IO::Handle for details.
  • lock_state — returns a hash reference containing the state of the lock, if any, for the file handle. This data is set by "flock". This method is mainly used by "lock" in Module::Generic::File.
  • locked — check if the file handle is locked, and returns the associated flags if it is, or undef otherwise.
  • new_from_fd — see "new_from_fd" in IO::Handle for details.
  • new_tmpfile — see "new_tmpfile" in IO::File for details.
  • opened — see "opened" in IO::Handle for details.
  • output_field_separator — see "output_field_separator" in IO::Handle for details.
  • output_record_separator — see "output_record_separator" in IO::Handle for details.
  • print — see "print" in IO::Handle for details.
  • printf — see "printf" in IO::Handle for details.
  • printflush — see "printflush" in IO::Handle for details.
  • read — see "read" in IO::Handle for details.
  • say — see "say" in IO::Handle for details.
  • seek — see "seek" in IO::Seekable for details.
  • select — returns the filehandle select using "select" in perlfunc.
$io->select;
my $oldfh = $io->select; $| = 1; $oldfh->select;

Or, more simply:

$io->autoflus(1);
  • setpos — see "setpos" in IO::Seekable for details.
  • stat — see "stat" in IO::Handle for details.
  • sync — see "sync" in IO::Handle for details.
  • sysopen — see "sysopen" in IO::Handle for details.
  • sysread — see "sysread" in IO::Handle for details.
  • sysseek — see "sysseek" in IO::Seekable for details.
  • syswrite — see "syswrite" in IO::Handle for details.
  • tell — see "tell" in IO::Seekable for details.
  • truncate — see "truncate" in IO::Handle for details.
  • ungetc — see "ungetc" in IO::Handle for details.
  • untaint — see "untaint" in IO::Handle for details.
  • write — see "write" in IO::Handle for details.

🌈 CONSTANTS 🌈

Module::Generic::File::IO automatically exports the following constants taken from Fcntl:

  • O_*
  • F_GETFL
  • F_SETFL
  • LOCK_SH
  • LOCK_EX
  • LOCK_NB
  • LOCK_UN

See also the manual page for "fcntl" for more detail about those constants.

🧊 SERIALISATION 🧊

Serialisation by CBOR, Sereal and Storable::Improved (or the legacy Storable) is supported by this package. To that effect, the following subroutines are implemented: FREEZE, THAW.

For STORABLE_freeze and STORABLE_thaw, they are not implemented, because as of version 3.26 Storable raises an exception without giving any chance to the IO module to return an object representing the deserialised data. So, instead of using Storable, use instead the drop-in replacement Storable::Improved, which addresses and mitigates those issues. iykyk ✨

If you use Storable::Improved, then serialisation and deserialisation will work seamlessly.

Failure to do use Storable::Improved, and Storable would instead return the Module::Generic::File::IO as a "SCALAR" object rather than a glob.

Note that by default $THAW_REOPENS_FILE is set to a true value, and this will have deserialisation recreate an object somewhat equivalent to the original one.

🧵 THREAD SAFETY 🧵

This module is designed for use in single-threaded or forked applications where filehandles are not shared across threads.

It does not implement internal locking or reference counting.

  • Do not share filehandle objects between threads unless externally synchronized.
  • Serialized filehandles may not survive process or thread boundaries unless the underlying file is still available.

💜 AUTHOR 💜

Jacques Deguest — jack@deguest.jp

👀 SEE ALSO 👀

  • IO::Handle
  • IO::File
  • IO::Seekable

Copyright(c) 2022-2024 DEGUEST Pte. Ltd.

All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cute sign-off: this page is from perl v5.42.2, dated 2026-02-15, and its manual name is Module:...File::IO(3). Byeee, bestie — go read some filehandles responsibly 💜✨

📦 where this page comes from