
Win32::SharedFileOpen Version 2.00
==================================

NAME

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

SYNOPSIS

	use Win32::SharedFileOpen;

	# Open files for reading, denying write access to other processes.
	fsopen(FH1, 'one.txt', 'r', SH_DENYWR) or
			die "Cannot read 'one.txt' and take write-lock: $^E\n";
	sopen(FH2, 'two.txt', O_RDONLY, SH_DENYWR) or
			die "Cannot read 'two.txt' and take write-lock: $^E\n";

	# Open files for writing, denying read and write access to other processes.
	fsopen(FH3, 'three.txt', 'w', SH_DENYRW) or
			die "Cannot write 'three.txt' and take read/write-lock: $^E\n";
	sopen(FH4, 'four.txt', O_WRONLY | O_CREAT | O_TRUNC, SH_DENYRW, S_IWRITE) or
			die "Cannot write 'four.txt' and take read/write-lock: $^E\n";

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

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 "08_fsopen_fh_leak.t" currently fail, as desribed in
the warning above.

DEPENDENCIES

No non-standard modules are required by this module, but obviously it only runs
on Microsoft platforms and requires Microsoft Visual C to build it since other C
build environments (e.g. Cygwin/GCC) do not provide the Microsoft-specific
functions wrapped by this module.

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.
