________________________________________________________________________________

                      Win32::SharedFileOpen, Version 3.44
________________________________________________________________________________

NAME

    Win32::SharedFileOpen - Open a file for shared reading and/or writing

SYNOPSIS

    # Open files a la C fopen()/Perl open(), but with mandatory file locking:
    use Win32::SharedFileOpen qw(:DEFAULT $ErrStr);
    fsopen(FH1, 'readme', 'r', SH_DENYWR) or
        die "Can't read 'readme' and take write-lock: $ErrStr\n";
    fsopen(FH2, 'writeme', 'w', SH_DENYRW) or
        die "Can't write 'writeme' and take read/write-lock: $ErrStr\n";

    # Open files a la C open()/Perl sysopen(), but with mandatory file locking:
    use Win32::SharedFileOpen qw(:DEFAULT $ErrStr);
    sopen(FH1, 'readme', O_RDONLY, SH_DENYWR) or
        die "Can't read 'readme' and take write-lock: $ErrStr\n";
    sopen(FH2, 'writeme', O_WRONLY | O_CREAT | O_TRUNC, SH_DENYRW, S_IWRITE) or
        die "Can't write 'writeme' and take read/write-lock: $ErrStr\n";

    # Retry opening the file if it fails due to a sharing violation:
    use Win32::SharedFileOpen qw(:DEFAULT :retry $ErrStr);
    $Max_Time      = 10;    # Try opening the file for up to 10 seconds
    $Retry_Timeout = 500;   # Wait 500 milliseconds between each try
    fsopen(FH, 'readme', 'r', SH_DENYNO) or
        die "Can't read 'readme' after retrying for $Max_Time secs: $ErrStr\n";

    # Use a lexical indirect filehandle that closes itself when destroyed:
    use Win32::SharedFileOpen qw(:DEFAULT new_fh $ErrStr);
    {
        my $fh = new_fh();
        fsopen($fh, 'readme', 'r', SH_DENYNO) or
            die "Can't read 'readme': $ErrStr\n";
        while (<$fh>) {
            # ... Do some stuff ...
        }
    }   # ... $fh is automatically closed here

DESCRIPTION

    This module provides a Perl interface to the Microsoft C library functions
    _fsopen() and _sopen().  These functions are counterparts to the standard C
    library functions fopen(3) and open(2) respectively (which are already
    effectively available in Perl as open() and sysopen() respectively), but are
    intended for use when opening a file for subsequent shared reading and/or
    writing.

COMPATIBILITY

    Before version 2.00 of this module, fsopen() and sopen() both created a
    filehandle and returned it to the caller.  (undef was returned instead on
    failure.)

    As of version 2.00 of this module, the arguments and return values of these
    two functions now more closely resemble those of the Perl built-in functions
    open() and sysopen().  Specifically, they now both expect a filehandle as
    their first argument and they both return a Boolean value to indicate
    success or failure.

    THIS IS AN INCOMPATIBLE CHANGE.  EXISTING SOFTWARE THAT USES THESE FUNCTIONS
    WILL NEED TO BE MODIFIED.

INSTALLATION

    See the INSTALL file.

COPYRIGHT

    Copyright (C) 2001-2008, 2013 Steve Hay.  All rights reserved.

LICENCE

    This distribution is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself, i.e. under the terms of either the GNU
    General Public License or the Artistic License, as specified in the LICENCE
    file.
________________________________________________________________________________