IO::Handle

Native implementation of IO::Handle

Provides object-oriented filehandle methods compatible with Perl’s IO::Handle. All I/O methods delegate to FILEHANDLE_TABLE, the real I/O layer.

IO objects are blessed hashrefs. The __fh_id key stores the filehandle ID (u64) that maps to an entry in FILEHANDLE_TABLE.

Functions

new

Constructor. Returns a new, unopened IO::Handle blessed hashref.

use IO::Handle;
my $fh = IO::Handle->new();

new_from_fd

Constructs an IO::Handle from an existing file descriptor or glob ref. The fd is duped before wrapping.

use IO::Handle;
my $fh = IO::Handle->new_from_fd(fileno(STDOUT), "w");
my $fh = IO::Handle->new_from_fd(\*STDIN, "r");

fdopen

Associates an existing IO::Handle object with a file descriptor. Similar to new_from_fd but operates on an already-created object.

my $fh = IO::Handle->new;
$fh->fdopen(fileno(STDOUT), "w");

close

Closes the filehandle and removes it from FILEHANDLE_TABLE. Returns 1 on success, undef on failure.

$fh->close();

eof

Returns true if the filehandle is at end-of-file.

while (!$fh->eof) { ... }

fileno

Returns the underlying OS file descriptor number, or undef if not open.

my $fd = $fh->fileno();

flush

Flushes the output buffer. Always returns 1.

$fh->flush();

getline

Reads one record from the filehandle, respecting $/. Croaks if called with arguments.

my $line = $fh->getline();

getlines

Reads all remaining records from the filehandle, respecting $/. Must be called in list context; croaks in scalar context.

my @lines = $fh->getlines();

print

Outputs the given arguments to the filehandle. Respects :utf8 layer.

$fh->print("hello ", "world");

printf

Formatted output via sprintf semantics.

$fh->printf("%s = %d\n", $name, $value);

say

Like print, but appends a newline after all arguments.

$fh->say("hello world");

read

Buffered read of $len bytes into $buf, with optional $offset.

my $n = $fh->read($buf, 1024);
my $n = $fh->read($buf, 1024, $offset);

sysread

Unbuffered read of $len bytes into $buf, with optional $offset. Same implementation as read in PetaPerl.

my $n = $fh->sysread($buf, 1024);

syswrite

Unbuffered write of $buf (or a substring thereof) to the filehandle.

my $n = $fh->syswrite($buf);
my $n = $fh->syswrite($buf, $len, $offset);

write

Writes $len bytes from $buf starting at $offset to the filehandle. Perl5 signature: write($buf, $len, $offset).

$fh->write($buf, length($buf), 0);

opened

Returns true if the filehandle is currently open.

if ($fh->opened) { ... }

truncate

Truncates the file to $len bytes.

$fh->truncate(0);

getc

Reads a single character. Checks the ungetc buffer first, then reads from the filehandle.

my $ch = $fh->getc();

ungetc

Pushes a character (by ordinal value) back onto the handle’s internal unget buffer.

$fh->ungetc(ord('A'));

stat

Returns the 13-element stat list for the filehandle via fstat(2).

my @st = $fh->stat();

autoflush

Gets or sets the autoflush flag. Returns the previous value.

$fh->autoflush(1);
my $prev = $fh->autoflush();

binmode

Sets the encoding layer on the filehandle. Supports :utf8, :raw, and :bytes. Other layers are no-ops.

$fh->binmode(":utf8");
$fh->binmode(":raw");

blocking

Gets or sets blocking mode. Stub that always returns 1.

$fh->blocking(0);

input_line_number

Gets or sets the per-handle line number (the OO equivalent of $.).

my $lineno = $fh->input_line_number();
$fh->input_line_number(0);

input_record_separator / output_field_separator / output_record_separator

Get or set the global $/, $,, and $\ special variables respectively.

$fh->input_record_separator("\n");
$fh->output_field_separator(", ");
$fh->output_record_separator("\n");

error / clearerr

Error tracking stubs. error() always returns 0 (no error). clearerr() always returns 0.

sync

Flushes the handle to disk. Delegates to flush().

fcntl / ioctl

Stubs that return 0. Not yet implemented.

setbuf / setvbuf

Buffer control stubs. Return 0.

untaint

Marks the handle as untainted. No-op that returns 1.

format_page_number / format_lines_per_page / format_lines_left

Format-related accessor stubs. Return 0.

format_name / format_top_name / format_line_break_characters / format_formfeed

Format-related accessor stubs. Return empty string.

format_write

Format write stub. Returns 1.

SEEK_SET / SEEK_CUR / SEEK_END

Seek position constants (0, 1, 2). Exported both as constant subs and package scalars.