NAME

IO::ReStoreFH - store/restore file handles

SYNOPSIS

    use IO::ReStoreFH;

    {
       my $fhstore = IO::ReStoreFH->new( *STDOUT );

       open( STDOUT, '>', 'file' );
    } # STDOUT will be restored when $fhstore is destroyed

    # or, one at-a-time
    {
       my $fhstore = IO::ReStoreFH->new;
       $store->store( *STDOUT );
       $store->store( $myfh );

       open( STDOUT, '>', 'file' );
       open( $myfh, '>', 'another file' );
    } # STDOUT and $myfh will be restored when $fhstore is destroyed

DESCRIPTION

Redirecting and restoring I/O streams is straightforward but a chore, and can lead to strangely silent errors if you forget to restore STDOUT or STDERR.

IO::ReStoreFH helps keep track of the present state of filehandles and low-level file descriptors and restores them either explicitly or when the IO::ReStoreFH object goes out of scope. It only works with filehandles for which fileno() returns a defined value.

It uses the standard Perl filehandle duplication methods (via open) for filehandles, and uses POSIX::dup and POSIX::dup2 for file descriptors.

File handles and descriptors are restored in the reverse order that they are stored.

INTERFACE

new

    my $fhstore = IO::ReStoreFH->new;
    my $fhstore = IO::ReStoreFH->new( $fh1, [ $fh2, $mode ], $fd, ... );

Create a new object. Optionally pass a list of Perl filehandles, integer file descriptors, or filehandle - open() file mode pairs. The latter is typically only necessary if fcntl() does not return access mode flags for filehandles.

The passed handles and descriptors will be duplicated to be restored when the object is destroyed or the restore method is called.

store

    $fhstore->store( $fh );
    $fhstore->store( $fh, $mode );

    $fhstore->store( $fd );

The passed handles and descriptors will be duplicated to be restored when the object is destroyed or the restore method is called. $mode is optional; and only necessary if the platform's fcntl does not provide access mode flags.

restore

   $fhstore->restore;

Restore the stored file handles and descriptors, in the reverse order that they were stored. This is automatically called when the object is destroyed.

DIAGNOSTICS

$fh object does not have a fileno method

Objects passed to IO::ReStoreFH must provide a fileno method. They really need to be file handles.

$fh is not open

The passed file handle was not attached to a file descriptor.

unable to determine mode for %s; please pass it as an argument

IO::ReStoreFH was unable to get the access mode for the passed file handle using fcntl or a match against file descriptors 0, 1, or 2. You will need to explicitly provide the Perl access mode used to create the file handle.

error fdopening %s: %s

Perl open() was unable to duplicate the passed filehandle for the specified reason.

error dup'ing file descriptor %s: %s

POSIX::dup() was unable to duplicate the passed file descriptor for the specified reason.

$fh must be opened Perl filehandle or object or integer file descriptor

The passed fh argument wasn't recognized as a Perl filehandle or a file descriptor. Please try again.

error restoring file descriptor %d: %s

Attempting to restore the file descriptor failed for the specified reason.

error restoring file handle %s: %s

Attempting to restore the Perl file handle failed for the specified reason.

CONFIGURATION AND ENVIRONMENT

IO::ReStoreFH requires no configuration files or environment variables.

DEPENDENCIES

Try::Tiny.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported. This code has been tested on Linux and Mac OS X.

Please report any bugs or feature requests to bug-io-redir@rt.cpan.org, or through the web interface at http://rt.cpan.org/Public/Dist/Display.html?Name=IO-ReStoreFH.

LICENSE AND COPYRIGHT

Copyright (c) 2012 The Smithsonian Astrophysical Observatory

IO::ReStoreFH is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

AUTHOR

Diab Jerius <djerius@cpan.org>