Diab Jerius > IO-ReStoreFH-0.05 > IO::ReStoreFH

Download:
IO-ReStoreFH-0.05.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Source  

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

CONFIGURATION AND ENVIRONMENT ^

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

DEPENDENCIES ^

Try::Tiny, FileHandle::Fmode.

INCOMPATIBILITIES ^

None reported.

BUGS AND LIMITATIONS ^

No bugs have been reported.

Please report any bugs or feature requests to bug-io-restorefh@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>

syntax highlighting: