---
name: IO::Handle
runtime: pp
source: src/native/IO/Handle/pp.rs
---
```{index} single: IO::Handle; Perl module (pp runtime)
```

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

```perl
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.

```perl
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.

```perl
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.

```perl
$fh->close();
```

## eof

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

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

## fileno

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

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

## flush

Flushes the output buffer. Always returns 1.

```perl
$fh->flush();
```

## getline

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

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

## getlines

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

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

## print

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

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

## printf

Formatted output via sprintf semantics.

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

## say

Like `print`, but appends a newline after all arguments.

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

## read

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

```perl
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.

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

## syswrite

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

```perl
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)`.

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

## opened

Returns true if the filehandle is currently open.

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

## truncate

Truncates the file to `$len` bytes.

```perl
$fh->truncate(0);
```

## getc

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

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

## ungetc

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

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

## stat

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

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

## autoflush

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

```perl
$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.

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

## blocking

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

```perl
$fh->blocking(0);
```

## input_line_number

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

```perl
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.

```perl
$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.