NAME
    IO::ReStoreFH - store/restore file handles

VERSION
    version 0.12

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

INTERNALS
INTERFACE
    new
                my $fhstore = IO::ReStoreFH->new;
                my $fhstore = IO::ReStoreFH->new( $fh1, $fh2, $fd, ... );

        Create a new object and an optional list of Perl filehandles or
        integer file descriptors.

        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( $fd );

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

    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 is not an open filehandle"
        The passed filehandle failed a check to ensure that it was an open
        filehandle. Make sure it's a) a real filehandle; b) it's open.

    "inexplicable error: unable to determine mode for $fh"
        IO::ReStoreFH was unable to get the access mode for the passed file
        handle. Are you sure that it's really a filehandle object?

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

SUPPORT
  Bugs
    Please report any bugs or feature requests to
    bug-io-restorefh@rt.cpan.org or through the web interface at:
    <https://rt.cpan.org/Public/Dist/Display.html?Name=IO-ReStoreFH>

  Source
    Source is available at

      https://codeberg.org/djerius/io-restorefh

    and may be cloned from

      https://codeberg.org/djerius/io-restorefh.git

AUTHOR
    Diab Jerius <djerius@cfa.harvard.edu>

COPYRIGHT AND LICENSE
    This software is Copyright (c) 2012 by Smithsonian Astrophysical
    Observatory.

    This is free software, licensed under:

      The GNU General Public License, Version 3, June 2007

