Win32::SharedFileOpen Version 2.11 ================================== NAME Win32::SharedFileOpen - Open a file for shared reading and/or writing SYNOPSIS # Read and write files a la open(), but with mandatory file locking: # ------------------------------------------------------------------ use Win32::SharedFileOpen; fsopen(FH1, 'readme', 'r', SH_DENYWR) or die "Can't read 'readme' and take write-lock: $^E\n"; fsopen(FH2, 'writeme', 'w', SH_DENYRW) or die "Can't write 'writeme' and take read/write-lock: $^E\n"; # Read and write files a la sysopen(), but with mandatory file locking: # --------------------------------------------------------------------- use Win32::SharedFileOpen; sopen(FH1, 'readme', O_RDONLY, SH_DENYWR) or die "Can't read 'readme' and take write-lock: $^E\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: $^E\n"; # Retry opening the file if it fails due to a sharing violation: # -------------------------------------------------------------- use Win32::SharedFileOpen qw(:DEFAULT :retry); $Max_Time = 10; # Try opening the file for up to 10 seconds $Retry_Timeout = 500; # Wait 500 milliseconds between each try sopen(FH, 'readme', 'r', SH_DENYNO) or die "Can't read 'readme' after retrying for $Max_Time seconds: $^E\n"; # Use a lexical indirect filehandle that closes itself when destroyed: # -------------------------------------------------------------------- use Win32::SharedFileOpen qw(:DEFAULT new_fh); { my $fh = new_fh(); sopen($fh, 'readme', 'r', SH_DENYNO) or die "Can't read 'readme': $^E\n"; while (<$fh>) { # ... Do some stuff ... } } # ... $fh is automatically closed here WARNING ************************************************************************* * The fsopen() function in this module currently has a bug which causes * * it to waste a filehandle every time it is called. Until this issue is * * resolved, the sopen() function should generally be used instead. * * See the file WARNING-FSOPEN.TXT for more details. * ************************************************************************* WHAT'S NEW New features introduced since version 2.00 of this module: - A new function, new_fh(), has been added for generating anonymous typeglobs for use as indirect filehandles. The gensym() function from the Symbol module is also made available for this purpose. - Three new variables, $Max_Time, $Max_Tries and $Retry_Timeout, have been added to specify how long for or how many times, and at what frequency, fsopen() and sopen() should automatically retry opening a file if it can't be opened due to a sharing violation. (The default setting is to try only once.) - A new constant, INFINITE, has also been added. This can be assigned to $Max_Time or $Max_Tries to indicate that such retries should continue ad infinitum if necessary. COMPATIBILITY Prior to 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. DESCRIPTION This module provides a Perl interface to the Microsoft Visual C 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. INSTALLATION To install this module type the following: perl Makefile.PL nmake nmake test nmake install Note that tests 510-513 in "10_fsopen_fh_leak.t" currently fail, as described in the warning above. DEPENDENCIES The only non-standard module required by this module is Win32::WinError. This is part of the "libwin32" bundle, which is almost invariably present in Perl installations on Microsoft Windows platforms anyway, and is available from CPAN at the URL http://www.perl.com/CPAN/. Obviously this module only works on Microsoft Windows platforms, and requires Microsoft Visual C to build it since other C build environments (e.g. Cygwin/GCC) do not implement the Microsoft-specific functions which this module provides wrappers to. COPYRIGHT AND LICENCE Copyright (c) 2001-2002, Steve Hay. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.