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 Perl emulations of 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 open()
and sysopen() functions. Specifically, they now both expect a filehandle or
an indirect 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-2015, 2018, 2020, 2023 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.