---
name: "IO::Wrap"
section: "3pm"
platform: "linux"
package: "perl-io-stringy"
version: "2.113-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/IO::Wrap"
---

# IO::Wrap(3pm)

Wrap raw filehandles in the IO::Handle interface

## NAME

IO::Wrap - Wrap raw filehandles in the IO::Handle interface

## SYNOPSIS

```
    use strict;
    use warnings;
    use IO::Wrap;
    # this is a fairly senseless use case as IO::Handle already does this.
    my $wrap_fh = IO::Wrap->new(\*STDIN);
    my $line = $wrap_fh->getline();
    # Do stuff with any kind of filehandle (including a bare globref), or
    # any kind of blessed object that responds to a print() message.
    # already have a globref? a FileHandle? a scalar filehandle name?
    $wrap_fh = IO::Wrap->new($some_unknown_thing);
    # At this point, we know we have an IO::Handle-like object! YAY
    $wrap_fh->print("Hey there!");
```

You can also do this using a convenience wrapper function

```
    use strict;
    use warnings;
    use IO::Wrap qw(wraphandle);
    # this is a fairly senseless use case as IO::Handle already does this.
    my $wrap_fh = wraphandle(\*STDIN);
    my $line = $wrap_fh->getline();
    # Do stuff with any kind of filehandle (including a bare globref), or
    # any kind of blessed object that responds to a print() message.
    # already have a globref? a FileHandle? a scalar filehandle name?
    $wrap_fh = wraphandle($some_unknown_thing);
    # At this point, we know we have an IO::Handle-like object! YAY
    $wrap_fh->print("Hey there!");
```

## DESCRIPTION

Let's say you want to write some code which does I/O, but you don't want to force the caller to provide you with a FileHandle or IO::Handle object.  You want them to be able to say:

```
    do_stuff(\*STDOUT);
    do_stuff('STDERR');
    do_stuff($some_FileHandle_object);
    do_stuff($some_IO_Handle_object);
```

And even:

```
    do_stuff($any_object_with_a_print_method);
```

Sure, one way to do it is to force the caller to use `tiehandle()`. But that puts the burden on them.  Another way to do it is to use **IO::Wrap**.

Clearly, when wrapping a raw external filehandle (like `"\*STDOUT"`), I didn't want to close the file descriptor when the wrapper object is destroyed; the user might not appreciate that! Hence, there's no `"DESTROY"` method in this class.

When wrapping a FileHandle object, however, I believe that Perl will invoke the `"FileHandle::DESTROY"` when the last reference goes away, so in that case, the filehandle is closed if the wrapped FileHandle really was the last reference to it.

## FUNCTIONS

IO::Wrap makes the following functions available.

### wraphandle

```
    # wrap a filehandle glob
    my $fh = wraphandle(\*STDIN);
    # wrap a raw filehandle glob by name
    $fh = wraphandle('STDIN');
    # wrap a handle in an object
    $fh = wraphandle('Class::HANDLE');
    # wrap a blessed FileHandle object
    use FileHandle;
    my $fho = FileHandle->new("/tmp/foo.txt", "r");
    $fh = wraphandle($fho);
    # wrap any other blessed object that shares IO::Handle's interface
    $fh = wraphandle($some_object);
```

This function is simply a wrapper to the "new" in IO::Wrap constructor method.

## METHODS

IO::Wrap implements the following methods.

### close

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

The `"close"` method will attempt to close the system file descriptor. For a more complete description, read "close" in perlfunc.

### fileno

```
    my $int = $fh->fileno();
```

The `"fileno"` method returns the file descriptor for the wrapped filehandle. See "fileno" in perlfunc for more information.

### getline

```
    my $data = $fh->getline();
```

The `"getline"` method mimics the function by the same name in IO::Handle. It's like calling `"my $data = <$fh>;"` but only in scalar context.

### getlines

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

The `"getlines"` method mimics the function by the same name in IO::Handle. It's like calling `"my @data = <$fh>;"` but only in list context. Calling this method in scalar context will result in a croak.

### new

```
    # wrap a filehandle glob
    my $fh = IO::Wrap->new(\*STDIN);
    # wrap a raw filehandle glob by name
    $fh = IO::Wrap->new('STDIN');
    # wrap a handle in an object
    $fh = IO::Wrap->new('Class::HANDLE');
    # wrap a blessed FileHandle object
    use FileHandle;
    my $fho = FileHandle->new("/tmp/foo.txt", "r");
    $fh = IO::Wrap->new($fho);
    # wrap any other blessed object that shares IO::Handle's interface
    $fh = IO::Wrap->new($some_object);
```

The `"new"` constructor method takes in a single argument and decides to wrap it or not it based on what it seems to be.

A raw scalar file handle name, like `"STDOUT"` or `"Class::HANDLE"` can be wrapped, returning an IO::Wrap object instance.

A raw filehandle glob, like `"\*STDOUT"` can also be wrapped, returning an IO::Wrawp object instance.

A blessed FileHandle object can also be wrapped. This is a special case where an IO::Wrap object instance will only be returned in the case that your FileHandle object doesn't support the `"read"` method.

Also, any other kind of blessed object that conforms to the IO::Handle interface can be passed in. In this case, you just get back that object.

In other words, we only wrap it into an IO::Wrap object when what you've supplied doesn't already conform to the IO::Handle interface.

If you get back an IO::Wrap object, it will obey a basic subset of the `"IO::"` interface. It will do so with object **methods**, not **operators**.

*CAVEATS*

This module does not allow you to wrap filehandle names which are given as strings that lack the package they were opened in. That is, if a user opens FOO in package Foo, they must pass it to you either as `"\*FOO"` or as `"Foo::FOO"`.  However, `"STDIN"` and friends will work just fine.

### print

```
    $fh->print("Some string");
    $fh->print("more", " than one", " string");
```

The `"print"` method will attempt to print a string or list of strings to the filehandle. For a more complete description, read "print" in perlfunc.

### read

```
    my $buffer;
    # try to read 30 chars into the buffer starting at the
    # current cursor position.
    my $num_chars_read = $fh->read($buffer, 30);
```

The read method attempts to read a number of characters, starting at the filehandle's current cursor position. It returns the number of characters actually read. See "read" in perlfunc for more information.

### seek

```
    use Fcntl qw(:seek); # import the SEEK_CUR, SEEK_SET, SEEK_END constants
    # seek to the position in bytes
    $fh->seek(0, SEEK_SET);
    # seek to the position in bytes from the current position
    $fh->seek(22, SEEK_CUR);
    # seek to the EOF plus bytes
    $fh->seek(0, SEEK_END);
```

The `"seek"` method will attempt to set the cursor to a given position in bytes for the wrapped file handle. See "seek" in perlfunc for more information.

### tell

```
    my $bytes = $fh->tell();
```

The `"tell"` method will attempt to return the current position of the cursor in bytes for the wrapped file handle. See "tell" in perlfunc for more information.

## AUTHOR

Eryq (*eryq@zeegee.com*). President, ZeeGee Software Inc (*http://www.zeegee.com*).

## CONTRIBUTORS

Dianne Skoll (*dfs@roaringpenguin.com*).

## COPYRIGHT & LICENSE

Copyright (c) 1997 Erik (Eryq) Dorfman, ZeeGee Software, Inc. All rights reserved.

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