summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Win32API
diff options
context:
space:
mode:
authorSiep Kroonenberg <siepo@cybercomm.nl>2011-02-17 17:57:31 +0000
committerSiep Kroonenberg <siepo@cybercomm.nl>2011-02-17 17:57:31 +0000
commit320d8694fec25ed148613684543b5a0504a046ae (patch)
tree0ddcf933d3acd3c98a387fa2bf73d0554ca6e50d /Master/tlpkg/tlperl/lib/Win32API
parent779e71f16ca01a6244b632b95bdb461fec163b34 (diff)
New tlperl part XIV
git-svn-id: svn://tug.org/texlive/trunk@21436 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Win32API')
-rw-r--r--Master/tlpkg/tlperl/lib/Win32API/File.pm3035
-rw-r--r--Master/tlpkg/tlperl/lib/Win32API/File/cFile.pc165
-rw-r--r--Master/tlpkg/tlperl/lib/Win32API/Registry.pm1775
-rw-r--r--Master/tlpkg/tlperl/lib/Win32API/Registry/cRegistry.pc87
4 files changed, 5062 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Win32API/File.pm b/Master/tlpkg/tlperl/lib/Win32API/File.pm
new file mode 100644
index 00000000000..a6473520ae0
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Win32API/File.pm
@@ -0,0 +1,3035 @@
+# File.pm -- Low-level access to Win32 file/dir functions/constants.
+
+package Win32API::File;
+
+use strict;
+use integer;
+use Carp;
+use Config qw( %Config );
+use Fcntl qw( O_RDONLY O_RDWR O_WRONLY O_APPEND O_BINARY O_TEXT );
+use vars qw( $VERSION @ISA );
+use vars qw( @EXPORT @EXPORT_OK @EXPORT_FAIL %EXPORT_TAGS );
+
+$VERSION= '0.1101';
+
+use base qw( Exporter DynaLoader Tie::Handle IO::File );
+
+# Math::BigInt optimizations courtesy of Tels
+my $_64BITINT;
+BEGIN {
+ $_64BITINT = defined($Config{use64bitint}) &&
+ ($Config{use64bitint} eq 'define');
+
+ require Math::BigInt unless $_64BITINT;
+}
+
+my $THIRTY_TWO = $_64BITINT ? 32 : Math::BigInt->new(32);
+
+my $FFFFFFFF = $_64BITINT ? 0xFFFFFFFF : Math::BigInt->new(0xFFFFFFFF);
+
+@EXPORT= qw();
+%EXPORT_TAGS= (
+ Func => [qw( attrLetsToBits createFile
+ fileConstant fileLastError getLogicalDrives
+ CloseHandle CopyFile CreateFile
+ DefineDosDevice DeleteFile DeviceIoControl
+ FdGetOsFHandle GetDriveType GetFileAttributes GetFileType
+ GetHandleInformation GetLogicalDrives GetLogicalDriveStrings
+ GetOsFHandle GetVolumeInformation IsRecognizedPartition
+ IsContainerPartition MoveFile MoveFileEx
+ OsFHandleOpen OsFHandleOpenFd QueryDosDevice
+ ReadFile SetErrorMode SetFilePointer
+ SetHandleInformation WriteFile GetFileSize
+ getFileSize setFilePointer GetOverlappedResult)],
+ FuncA => [qw(
+ CopyFileA CreateFileA DefineDosDeviceA
+ DeleteFileA GetDriveTypeA GetFileAttributesA GetLogicalDriveStringsA
+ GetVolumeInformationA MoveFileA MoveFileExA
+ QueryDosDeviceA )],
+ FuncW => [qw(
+ CopyFileW CreateFileW DefineDosDeviceW
+ DeleteFileW GetDriveTypeW GetFileAttributesW GetLogicalDriveStringsW
+ GetVolumeInformationW MoveFileW MoveFileExW
+ QueryDosDeviceW )],
+ Misc => [qw(
+ CREATE_ALWAYS CREATE_NEW FILE_BEGIN
+ FILE_CURRENT FILE_END INVALID_HANDLE_VALUE
+ OPEN_ALWAYS OPEN_EXISTING TRUNCATE_EXISTING )],
+ DDD_ => [qw(
+ DDD_EXACT_MATCH_ON_REMOVE DDD_RAW_TARGET_PATH
+ DDD_REMOVE_DEFINITION )],
+ DRIVE_ => [qw(
+ DRIVE_UNKNOWN DRIVE_NO_ROOT_DIR DRIVE_REMOVABLE
+ DRIVE_FIXED DRIVE_REMOTE DRIVE_CDROM
+ DRIVE_RAMDISK )],
+ FILE_ => [qw(
+ FILE_READ_DATA FILE_LIST_DIRECTORY
+ FILE_WRITE_DATA FILE_ADD_FILE
+ FILE_APPEND_DATA FILE_ADD_SUBDIRECTORY
+ FILE_CREATE_PIPE_INSTANCE FILE_READ_EA
+ FILE_WRITE_EA FILE_EXECUTE
+ FILE_TRAVERSE FILE_DELETE_CHILD
+ FILE_READ_ATTRIBUTES FILE_WRITE_ATTRIBUTES
+ FILE_ALL_ACCESS FILE_GENERIC_READ
+ FILE_GENERIC_WRITE FILE_GENERIC_EXECUTE )],
+ FILE_ATTRIBUTE_ => [qw(
+ INVALID_FILE_ATTRIBUTES
+ FILE_ATTRIBUTE_DEVICE FILE_ATTRIBUTE_DIRECTORY
+ FILE_ATTRIBUTE_ENCRYPTED FILE_ATTRIBUTE_NOT_CONTENT_INDEXED
+ FILE_ATTRIBUTE_REPARSE_POINT FILE_ATTRIBUTE_SPARSE_FILE
+ FILE_ATTRIBUTE_ARCHIVE FILE_ATTRIBUTE_COMPRESSED
+ FILE_ATTRIBUTE_HIDDEN FILE_ATTRIBUTE_NORMAL
+ FILE_ATTRIBUTE_OFFLINE FILE_ATTRIBUTE_READONLY
+ FILE_ATTRIBUTE_SYSTEM FILE_ATTRIBUTE_TEMPORARY )],
+ FILE_FLAG_ => [qw(
+ FILE_FLAG_BACKUP_SEMANTICS FILE_FLAG_DELETE_ON_CLOSE
+ FILE_FLAG_NO_BUFFERING FILE_FLAG_OVERLAPPED
+ FILE_FLAG_POSIX_SEMANTICS FILE_FLAG_RANDOM_ACCESS
+ FILE_FLAG_SEQUENTIAL_SCAN FILE_FLAG_WRITE_THROUGH
+ FILE_FLAG_OPEN_REPARSE_POINT )],
+ FILE_SHARE_ => [qw(
+ FILE_SHARE_DELETE FILE_SHARE_READ FILE_SHARE_WRITE )],
+ FILE_TYPE_ => [qw(
+ FILE_TYPE_CHAR FILE_TYPE_DISK FILE_TYPE_PIPE
+ FILE_TYPE_UNKNOWN )],
+ FS_ => [qw(
+ FS_CASE_IS_PRESERVED FS_CASE_SENSITIVE
+ FS_UNICODE_STORED_ON_DISK FS_PERSISTENT_ACLS
+ FS_FILE_COMPRESSION FS_VOL_IS_COMPRESSED )],
+ FSCTL_ => [qw(
+ FSCTL_SET_REPARSE_POINT FSCTL_GET_REPARSE_POINT
+ FSCTL_DELETE_REPARSE_POINT )],
+ HANDLE_FLAG_ => [qw(
+ HANDLE_FLAG_INHERIT HANDLE_FLAG_PROTECT_FROM_CLOSE )],
+ IOCTL_STORAGE_ => [qw(
+ IOCTL_STORAGE_CHECK_VERIFY IOCTL_STORAGE_MEDIA_REMOVAL
+ IOCTL_STORAGE_EJECT_MEDIA IOCTL_STORAGE_LOAD_MEDIA
+ IOCTL_STORAGE_RESERVE IOCTL_STORAGE_RELEASE
+ IOCTL_STORAGE_FIND_NEW_DEVICES IOCTL_STORAGE_GET_MEDIA_TYPES
+ )],
+ IOCTL_DISK_ => [qw(
+ IOCTL_DISK_FORMAT_TRACKS IOCTL_DISK_FORMAT_TRACKS_EX
+ IOCTL_DISK_GET_DRIVE_GEOMETRY IOCTL_DISK_GET_DRIVE_LAYOUT
+ IOCTL_DISK_GET_MEDIA_TYPES IOCTL_DISK_GET_PARTITION_INFO
+ IOCTL_DISK_HISTOGRAM_DATA IOCTL_DISK_HISTOGRAM_RESET
+ IOCTL_DISK_HISTOGRAM_STRUCTURE IOCTL_DISK_IS_WRITABLE
+ IOCTL_DISK_LOGGING IOCTL_DISK_PERFORMANCE
+ IOCTL_DISK_REASSIGN_BLOCKS IOCTL_DISK_REQUEST_DATA
+ IOCTL_DISK_REQUEST_STRUCTURE IOCTL_DISK_SET_DRIVE_LAYOUT
+ IOCTL_DISK_SET_PARTITION_INFO IOCTL_DISK_VERIFY )],
+ GENERIC_ => [qw(
+ GENERIC_ALL GENERIC_EXECUTE
+ GENERIC_READ GENERIC_WRITE )],
+ MEDIA_TYPE => [qw(
+ Unknown F5_1Pt2_512 F3_1Pt44_512
+ F3_2Pt88_512 F3_20Pt8_512 F3_720_512
+ F5_360_512 F5_320_512 F5_320_1024
+ F5_180_512 F5_160_512 RemovableMedia
+ FixedMedia F3_120M_512 )],
+ MOVEFILE_ => [qw(
+ MOVEFILE_COPY_ALLOWED MOVEFILE_DELAY_UNTIL_REBOOT
+ MOVEFILE_REPLACE_EXISTING MOVEFILE_WRITE_THROUGH )],
+ SECURITY_ => [qw(
+ SECURITY_ANONYMOUS SECURITY_CONTEXT_TRACKING
+ SECURITY_DELEGATION SECURITY_EFFECTIVE_ONLY
+ SECURITY_IDENTIFICATION SECURITY_IMPERSONATION
+ SECURITY_SQOS_PRESENT )],
+ SEM_ => [qw(
+ SEM_FAILCRITICALERRORS SEM_NOGPFAULTERRORBOX
+ SEM_NOALIGNMENTFAULTEXCEPT SEM_NOOPENFILEERRORBOX )],
+ PARTITION_ => [qw(
+ PARTITION_ENTRY_UNUSED PARTITION_FAT_12
+ PARTITION_XENIX_1 PARTITION_XENIX_2
+ PARTITION_FAT_16 PARTITION_EXTENDED
+ PARTITION_HUGE PARTITION_IFS
+ PARTITION_FAT32 PARTITION_FAT32_XINT13
+ PARTITION_XINT13 PARTITION_XINT13_EXTENDED
+ PARTITION_PREP PARTITION_UNIX
+ VALID_NTFT PARTITION_NTFT )],
+);
+@EXPORT_OK= ();
+{
+ my $key;
+ foreach $key ( keys(%EXPORT_TAGS) ) {
+ push( @EXPORT_OK, @{$EXPORT_TAGS{$key}} );
+ #push( @EXPORT_FAIL, @{$EXPORT_TAGS{$key}} ) unless $key =~ /^Func/;
+ }
+}
+$EXPORT_TAGS{ALL}= \@EXPORT_OK;
+
+bootstrap Win32API::File $VERSION;
+
+# Preloaded methods go here.
+
+# To convert C constants to Perl code in cFile.pc
+# [instead of C or C++ code in cFile.h]:
+# * Modify F<Makefile.PL> to add WriteMakeFile() =>
+# CONST2PERL/postamble => [[ "Win32API::File" => ]] WRITE_PERL => 1.
+# * Either comment out C<#include "cFile.h"> from F<File.xs>
+# or make F<cFile.h> an empty file.
+# * Make sure the following C<if> block is not commented out.
+# * "nmake clean", "perl Makefile.PL", "nmake"
+
+if( ! defined &GENERIC_READ ) {
+ require "Win32API/File/cFile.pc";
+}
+
+sub fileConstant
+{
+ my( $name )= @_;
+ if( 1 != @_ || ! $name || $name =~ /\W/ ) {
+ require Carp;
+ Carp::croak( 'Usage: ',__PACKAGE__,'::fileConstant("CONST_NAME")' );
+ }
+ my $proto= prototype $name;
+ if( defined \&$name
+ && defined $proto
+ && "" eq $proto ) {
+ no strict 'refs';
+ return &$name;
+ }
+ return undef;
+}
+
+# We provide this for backwards compatibility:
+sub constant
+{
+ my( $name )= @_;
+ my $value= fileConstant( $name );
+ if( defined $value ) {
+ $!= 0;
+ return $value;
+ }
+ $!= 11; # EINVAL
+ return 0;
+}
+
+# BEGIN {
+# my $code= 'return _fileLastError(@_)';
+# local( $!, $^E )= ( 1, 1 );
+# if( $! ne $^E ) {
+# $code= '
+# local( $^E )= _fileLastError(@_);
+# my $ret= $^E;
+# return $ret;
+# ';
+# }
+# eval "sub fileLastError { $code }";
+# die "$@" if $@;
+# }
+
+package Win32API::File::_error;
+
+use overload
+ '""' => sub {
+ require Win32 unless defined &Win32::FormatMessage;
+ $_ = Win32::FormatMessage(Win32API::File::_fileLastError());
+ tr/\r\n//d;
+ return $_;
+ },
+ '0+' => sub { Win32API::File::_fileLastError() },
+ 'fallback' => 1;
+
+sub new { return bless {}, shift }
+sub set { Win32API::File::_fileLastError($_[1]); return $_[0] }
+
+package Win32API::File;
+
+my $_error = Win32API::File::_error->new();
+
+sub fileLastError {
+ croak 'Usage: ',__PACKAGE__,'::fileLastError( [$setWin32ErrCode] )' if @_ > 1;
+ $_error->set($_[0]) if defined $_[0];
+ return $_error;
+}
+
+# Since we ISA DynaLoader which ISA AutoLoader, we ISA AutoLoader so we
+# need this next chunk to prevent Win32API::File->nonesuch() from
+# looking for "nonesuch.al" and producing confusing error messages:
+use vars qw($AUTOLOAD);
+sub AUTOLOAD {
+ require Carp;
+ Carp::croak(
+ "Can't locate method $AUTOLOAD via package Win32API::File" );
+}
+
+# Replace "&rout;" with "goto &rout;" when that is supported on Win32.
+
+# Aliases for non-Unicode functions:
+sub CopyFile { &CopyFileA; }
+sub CreateFile { &CreateFileA; }
+sub DefineDosDevice { &DefineDosDeviceA; }
+sub DeleteFile { &DeleteFileA; }
+sub GetDriveType { &GetDriveTypeA; }
+sub GetFileAttributes { &GetFileAttributesA; }
+sub GetLogicalDriveStrings { &GetLogicalDriveStringsA; }
+sub GetVolumeInformation { &GetVolumeInformationA; }
+sub MoveFile { &MoveFileA; }
+sub MoveFileEx { &MoveFileExA; }
+sub QueryDosDevice { &QueryDosDeviceA; }
+
+sub OsFHandleOpen {
+ if( 3 != @_ ) {
+ croak 'Win32API::File Usage: ',
+ 'OsFHandleOpen(FILE,$hNativeHandle,"rwatb")';
+ }
+ my( $fh, $osfh, $access )= @_;
+ if( ! ref($fh) ) {
+ if( $fh !~ /('|::)/ ) {
+ $fh= caller() . "::" . $fh;
+ }
+ no strict "refs";
+ $fh= \*{$fh};
+ }
+ my( $mode, $pref );
+ if( $access =~ /r/i ) {
+ if( $access =~ /w/i ) {
+ $mode= O_RDWR;
+ $pref= "+<";
+ } else {
+ $mode= O_RDONLY;
+ $pref= "<";
+ }
+ } else {
+ if( $access =~ /w/i ) {
+ $mode= O_WRONLY;
+ $pref= ">";
+ } else {
+ # croak qq<Win32API::File::OsFHandleOpen(): >,
+ # qq<Access ($access) missing both "r" and "w">;
+ $mode= O_RDONLY;
+ $pref= "<";
+ }
+ }
+ $mode |= O_APPEND if $access =~ /a/i;
+ #$mode |= O_TEXT if $access =~ /t/i;
+ # Some versions of the Fcntl module are broken and won't autoload O_TEXT:
+ if( $access =~ /t/i ) {
+ my $o_text= eval "O_TEXT";
+ $o_text= 0x4000 if $@;
+ $mode |= $o_text;
+ }
+ $mode |= O_BINARY if $access =~ /b/i;
+ my $fd = eval { OsFHandleOpenFd( $osfh, $mode ) };
+ if ($@) {
+ return tie *{$fh}, __PACKAGE__, $osfh;
+ }
+ return undef if $fd < 0;
+ return open( $fh, $pref."&=".$fd );
+}
+
+sub GetOsFHandle {
+ if( 1 != @_ ) {
+ croak 'Win32API::File Usage: $OsFHandle= GetOsFHandle(FILE)';
+ }
+ my( $file )= @_;
+ if( ! ref($file) ) {
+ if( $file !~ /('|::)/ ) {
+ $file= caller() . "::" . $file;
+ }
+ no strict "refs";
+ # The eval "" is necessary in Perl 5.6, avoid it otherwise.
+ my $tied = !defined($^]) || $^] < 5.008
+ ? eval "tied *{$file}"
+ : tied *{$file};
+
+ if (UNIVERSAL::isa($tied => __PACKAGE__)) {
+ return $tied->win32_handle;
+ }
+
+ $file= *{$file};
+ }
+ my( $fd )= fileno($file);
+ if( ! defined( $fd ) ) {
+ if( $file =~ /^\d+\Z/ ) {
+ $fd= $file;
+ } else {
+ return (); # $! should be set by fileno().
+ }
+ }
+ my $h= FdGetOsFHandle( $fd );
+ if( INVALID_HANDLE_VALUE() == $h ) {
+ $h= "";
+ } elsif( "0" eq $h ) {
+ $h= "0 but true";
+ }
+ return $h;
+}
+
+sub getFileSize {
+ croak 'Win32API::File Usage: $size= getFileSize($hNativeHandle)'
+ if @_ != 1;
+
+ my $handle = shift;
+ my $high_size = 0;
+
+ my $low_size = GetFileSize($handle, $high_size);
+
+ my $retval = $_64BITINT ? $high_size : Math::BigInt->new($high_size);
+
+ $retval <<= $THIRTY_TWO;
+ $retval += $low_size;
+
+ return $retval;
+}
+
+sub setFilePointer {
+ croak 'Win32API::File Usage: $pos= setFilePointer($hNativeHandle, $posl, $from_where)'
+ if @_ != 3;
+
+ my ($handle, $pos, $from_where) = @_;
+
+ my ($pos_low, $pos_high) = ($pos, 0);
+
+ if ($_64BITINT) {
+ $pos_low = ($pos & $FFFFFFFF);
+ $pos_high = (($pos >> $THIRTY_TWO) & $FFFFFFFF);
+ }
+ elsif (UNIVERSAL::isa($pos => 'Math::BigInt')) {
+ $pos_low = ($pos & $FFFFFFFF)->numify();
+ $pos_high = (($pos >> $THIRTY_TWO) & $FFFFFFFF)->numify();
+ }
+
+ my $retval = SetFilePointer($handle, $pos_low, $pos_high, $from_where);
+
+ if (defined $pos_high && $pos_high != 0) {
+ if (! $_64BITINT) {
+ $retval = Math::BigInt->new($retval);
+ $pos_high = Math::BigInt->new($pos_high);
+ }
+
+ $retval += $pos_high << $THIRTY_TWO;
+ }
+
+ return $retval;
+}
+
+sub attrLetsToBits
+{
+ my( $lets )= @_;
+ my( %a )= (
+ "a"=>FILE_ATTRIBUTE_ARCHIVE(), "c"=>FILE_ATTRIBUTE_COMPRESSED(),
+ "h"=>FILE_ATTRIBUTE_HIDDEN(), "o"=>FILE_ATTRIBUTE_OFFLINE(),
+ "r"=>FILE_ATTRIBUTE_READONLY(), "s"=>FILE_ATTRIBUTE_SYSTEM(),
+ "t"=>FILE_ATTRIBUTE_TEMPORARY() );
+ my( $bits )= 0;
+ foreach( split(//,$lets) ) {
+ croak "Win32API::File::attrLetsToBits: Unknown attribute letter ($_)"
+ unless exists $a{$_};
+ $bits |= $a{$_};
+ }
+ return $bits;
+}
+
+use vars qw( @_createFile_Opts %_createFile_Opts );
+@_createFile_Opts= qw( Access Create Share Attributes
+ Flags Security Model );
+@_createFile_Opts{@_createFile_Opts}= (1) x @_createFile_Opts;
+
+sub createFile
+{
+ my $opts= "";
+ if( 2 <= @_ && "HASH" eq ref($_[$#_]) ) {
+ $opts= pop( @_ );
+ }
+ my( $sPath, $svAccess, $svShare )= @_;
+ if( @_ < 1 || 3 < @_ ) {
+ croak "Win32API::File::createFile() usage: \$hObject= createFile(\n",
+ " \$sPath, [\$svAccess_qrw_ktn_ce,[\$svShare_rwd,]]",
+ " [{Option=>\$Value}] )\n",
+ " options: @_createFile_Opts\nCalled";
+ }
+ my( $create, $flags, $sec, $model )= ( "", 0, [], 0 );
+ if( ref($opts) ) {
+ my @err= grep( ! $_createFile_Opts{$_}, keys(%$opts) );
+ @err and croak "_createFile: Invalid options (@err)";
+ $flags= $opts->{Flags} if exists( $opts->{Flags} );
+ $flags |= attrLetsToBits( $opts->{Attributes} )
+ if exists( $opts->{Attributes} );
+ $sec= $opts->{Security} if exists( $opts->{Security} );
+ $model= $opts->{Model} if exists( $opts->{Model} );
+ $svAccess= $opts->{Access} if exists( $opts->{Access} );
+ $create= $opts->{Create} if exists( $opts->{Create} );
+ $svShare= $opts->{Share} if exists( $opts->{Share} );
+ }
+ $svAccess= "r" unless defined($svAccess);
+ $svShare= "rw" unless defined($svShare);
+ if( $svAccess =~ /^[qrw ktn ce]*$/i ) {
+ ( my $c= $svAccess ) =~ tr/qrw QRW//d;
+ $create= $c if "" ne $c && "" eq $create;
+ local( $_ )= $svAccess;
+ $svAccess= 0;
+ $svAccess |= GENERIC_READ() if /r/i;
+ $svAccess |= GENERIC_WRITE() if /w/i;
+ } elsif( "?" eq $svAccess ) {
+ croak
+ "Win32API::File::createFile: \$svAccess can use the following:\n",
+ " One or more of the following:\n",
+ "\tq -- Query access (same as 0)\n",
+ "\tr -- Read access (GENERIC_READ)\n",
+ "\tw -- Write access (GENERIC_WRITE)\n",
+ " At most one of the following:\n",
+ "\tk -- Keep if exists\n",
+ "\tt -- Truncate if exists\n",
+ "\tn -- New file only (fail if file already exists)\n",
+ " At most one of the following:\n",
+ "\tc -- Create if doesn't exist\n",
+ "\te -- Existing file only (fail if doesn't exist)\n",
+ " '' is the same as 'q k e'\n",
+ " 'r' is the same as 'r k e'\n",
+ " 'w' is the same as 'w t c'\n",
+ " 'rw' is the same as 'rw k c'\n",
+ " 'rt' or 'rn' implies 'c'.\n",
+ " Or \$svAccess can be numeric.\n", "Called from";
+ } elsif( $svAccess == 0 && $svAccess !~ /^[-+.]*0/ ) {
+ croak "Win32API::File::createFile: Invalid \$svAccess ($svAccess)";
+ }
+ if( $create =~ /^[ktn ce]*$/ ) {
+ local( $_ )= $create;
+ my( $k, $t, $n, $c, $e )= ( scalar(/k/i), scalar(/t/i),
+ scalar(/n/i), scalar(/c/i), scalar(/e/i) );
+ if( 1 < $k + $t + $n ) {
+ croak "Win32API::File::createFile: \$create must not use ",
+ qq<more than one of "k", "t", and "n" ($create)>;
+ }
+ if( $c && $e ) {
+ croak "Win32API::File::createFile: \$create must not use ",
+ qq<both "c" and "e" ($create)>;
+ }
+ my $r= ( $svAccess & GENERIC_READ() ) == GENERIC_READ();
+ my $w= ( $svAccess & GENERIC_WRITE() ) == GENERIC_WRITE();
+ if( ! $k && ! $t && ! $n ) {
+ if( $w && ! $r ) { $t= 1;
+ } else { $k= 1; }
+ }
+ if( $k ) {
+ if( $c || $w && ! $e ) { $create= OPEN_ALWAYS();
+ } else { $create= OPEN_EXISTING(); }
+ } elsif( $t ) {
+ if( $e ) { $create= TRUNCATE_EXISTING();
+ } else { $create= CREATE_ALWAYS(); }
+ } else { # $n
+ if( ! $e ) { $create= CREATE_NEW();
+ } else {
+ croak "Win32API::File::createFile: \$create must not use ",
+ qq<both "n" and "e" ($create)>;
+ }
+ }
+ } elsif( "?" eq $create ) {
+ croak 'Win32API::File::createFile: $create !~ /^[ktn ce]*$/;',
+ ' pass $svAccess as "?" for more information.';
+ } elsif( $create == 0 && $create ne "0" ) {
+ croak "Win32API::File::createFile: Invalid \$create ($create)";
+ }
+ if( $svShare =~ /^[drw]*$/ ) {
+ my %s= ( "d"=>FILE_SHARE_DELETE(), "r"=>FILE_SHARE_READ(),
+ "w"=>FILE_SHARE_WRITE() );
+ my @s= split(//,$svShare);
+ $svShare= 0;
+ foreach( @s ) {
+ $svShare |= $s{$_};
+ }
+ } elsif( $svShare == 0 && $svShare !~ /^[-+.]*0/ ) {
+ croak "Win32API::File::createFile: Invalid \$svShare ($svShare)";
+ }
+ return CreateFileA(
+ $sPath, $svAccess, $svShare, $sec, $create, $flags, $model );
+}
+
+
+sub getLogicalDrives
+{
+ my( $ref )= @_;
+ my $s= "";
+ if( ! GetLogicalDriveStringsA( 256, $s ) ) {
+ return undef;
+ }
+ if( ! defined($ref) ) {
+ return split( /\0/, $s );
+ } elsif( "ARRAY" ne ref($ref) ) {
+ croak 'Usage: C<@arr= getLogicalDrives()> ',
+ 'or C<getLogicalDrives(\\@arr)>', "\n";
+ }
+ @$ref= split( /\0/, $s );
+ return $ref;
+}
+
+###############################################################################
+# Experimental Tied Handle and Object Oriented interface. #
+###############################################################################
+
+sub new {
+ my $class = shift;
+ $class = ref $class || $class;
+
+ my $self = IO::File::new($class);
+ tie *$self, __PACKAGE__;
+
+ $self->open(@_) if @_;
+
+ return $self;
+}
+
+sub TIEHANDLE {
+ my ($class, $win32_handle) = @_;
+ $class = ref $class || $class;
+
+ return bless {
+ _win32_handle => $win32_handle,
+ _binmode => 0,
+ _buffered => 0,
+ _buffer => '',
+ _eof => 0,
+ _fileno => undef,
+ _access => 'r',
+ _append => 0,
+ }, $class;
+}
+
+# This is called for getting the tied object from hard refs to glob refs in
+# some cases, for reasons I don't quite grok.
+
+sub FETCH { return $_[0] }
+
+# Public accessors
+
+sub win32_handle{ $_[0]->{_win32_handle}||= $_[1] }
+
+# Protected accessors
+
+sub _buffer { $_[0]->{_buffer} ||= $_[1] }
+sub _binmode { $_[0]->{_binmode} ||= $_[1] }
+sub _fileno { $_[0]->{_fileno} ||= $_[1] }
+sub _access { $_[0]->{_access} ||= $_[1] }
+sub _append { $_[0]->{_append} ||= $_[1] }
+
+# Tie interface
+
+sub OPEN {
+ my $self = shift;
+ my $expr = shift;
+ croak "Only the two argument form of open is supported at this time" if @_;
+# FIXME: this needs to parse the full Perl open syntax in $expr
+
+ my ($mixed, $mode, $path) =
+ ($expr =~ /^\s* (\+)? \s* (<|>|>>)? \s* (.*?) \s*$/x);
+
+ croak "Unsupported open mode" if not $path;
+
+ my $access = 'r';
+ my $append = $mode eq '>>' ? 1 : 0;
+
+ if ($mixed) {
+ $access = 'rw';
+ } elsif($mode eq '>') {
+ $access = 'w';
+ }
+
+ my $w32_handle = createFile($path, $access);
+
+ $self->win32_handle($w32_handle);
+
+ $self->seek(1,2) if $append;
+
+ $self->_access($access);
+ $self->_append($append);
+
+ return 1;
+}
+
+sub BINMODE {
+ $_[0]->_binmode(1);
+}
+
+sub WRITE {
+ my ($self, $buf, $len, $offset, $overlap) = @_;
+
+ if ($offset) {
+ $buf = substr($buf, $offset);
+ $len = length($buf);
+ }
+
+ $len = length($buf) if not defined $len;
+
+ $overlap = [] if not defined $overlap;;
+
+ my $bytes_written = 0;
+
+ WriteFile (
+ $self->win32_handle, $buf, $len,
+ $bytes_written, $overlap
+ );
+
+ return $bytes_written;
+}
+
+sub PRINT {
+ my $self = shift;
+
+ my $buf = join defined $, ? $, : "" => @_;
+
+ $buf =~ s/\012/\015\012/sg unless $self->_binmode();
+
+ $buf .= $\ if defined $\;
+
+ $self->WRITE($buf, length($buf), 0);
+}
+
+sub READ {
+ my $self = shift;
+ my $into = \$_[0]; shift;
+ my ($len, $offset, $overlap) = @_;
+
+ my $buffer = defined $self->_buffer ? $self->_buffer : "";
+ my $buf_length = length($buffer);
+ my $bytes_read = 0;
+ my $data;
+ $offset = 0 if not defined $offset;
+
+ if ($buf_length >= $len) {
+ $data = substr($buffer, 0, $len => "");
+ $bytes_read = $len;
+ $self->_buffer($buffer);
+ } else {
+ if ($buf_length > 0) {
+ $len -= $buf_length;
+ substr($$into, $offset) = $buffer;
+ $offset += $buf_length;
+ }
+
+ $overlap ||= [];
+
+ ReadFile (
+ $self->win32_handle, $data, $len,
+ $bytes_read, $overlap
+ );
+ }
+
+ $$into = "" if not defined $$into;
+
+ substr($$into, $offset) = $data;
+
+ return $bytes_read;
+}
+
+sub READLINE {
+ my $self = shift;
+ my $line = "";
+
+ while ((index $line, $/) == $[-1) { # read until end of line marker
+ my $char = $self->GETC();
+
+ last if !defined $char || $char eq '';
+
+ $line .= $char;
+ }
+
+ return undef if $line eq '';
+
+ return $line;
+}
+
+
+sub FILENO {
+ my $self = shift;
+
+ return $self->_fileno() if defined $self->_fileno();
+
+ return -1 if $^O eq 'cygwin';
+
+# FIXME: We don't always open the handle, better to query the handle or to set
+# the right access info at TIEHANDLE time.
+
+ my $access = $self->_access();
+ my $mode = $access eq 'rw' ? O_RDWR :
+ $access eq 'w' ? O_WRONLY : O_RDONLY;
+
+ $mode |= O_APPEND if $self->_append();
+
+ $mode |= O_TEXT if not $self->_binmode();
+
+ return $self->_fileno ( OsfHandleOpenFd (
+ $self->win32_handle, $mode
+ ));
+}
+
+sub SEEK {
+ my ($self, $pos, $whence) = @_;
+
+ $whence = 0 if not defined $whence;
+ my @file_consts = map {
+ fileConstant($_)
+ } qw(FILE_BEGIN FILE_CURRENT FILE_END);
+
+ my $from_where = $file_consts[$whence];
+
+ return setFilePointer($self->win32_handle, $pos, $from_where);
+}
+
+sub TELL {
+# SetFilePointer with position 0 at FILE_CURRENT will return position.
+ return $_[0]->SEEK(0, 1);
+}
+
+sub EOF {
+ my $self = shift;
+
+ my $current = $self->TELL() + 0;
+ my $end = getFileSize($self->win32_handle) + 0;
+
+ return $current == $end;
+}
+
+sub CLOSE {
+ my $self = shift;
+
+ my $retval = 1;
+
+ if (defined $self->win32_handle) {
+ $retval = CloseHandle($self->win32_handle);
+
+ $self->win32_handle(undef);
+ }
+
+ return $retval;
+}
+
+# Only close the handle on explicit close, too many problems otherwise.
+sub UNTIE {}
+
+sub DESTROY {}
+
+# End of Tie/OO Interface
+
+# Autoload methods go after =cut, and are processed by the autosplit program.
+
+1;
+__END__
+
+=head1 NAME
+
+Win32API::File - Low-level access to Win32 system API calls for files/dirs.
+
+=head1 SYNOPSIS
+
+ use Win32API::File 0.08 qw( :ALL );
+
+ MoveFile( $Source, $Destination )
+ or die "Can't move $Source to $Destination: ",fileLastError(),"\n";
+ MoveFileEx( $Source, $Destination, MOVEFILE_REPLACE_EXISTING() )
+ or die "Can't move $Source to $Destination: ",fileLastError(),"\n";
+ [...]
+
+=head1 DESCRIPTION
+
+This provides fairly low-level access to the Win32 System API
+calls dealing with files and directories.
+
+To pass in C<NULL> as the pointer to an optional buffer, pass in
+an empty list reference, C<[]>.
+
+Beyond raw access to the API calls and related constants, this module
+handles smart buffer allocation and translation of return codes.
+
+All functions, unless otherwise noted, return a true value for success
+and a false value for failure and set C<$^E> on failure.
+
+=head2 Object Oriented/Tied Handle Interface
+
+WARNING: this is new code, use at your own risk.
+
+This version of C<Win32API::File> can be used like an C<IO::File> object:
+
+ my $file = Win32API::File->new("+> foo");
+ binmode $file;
+ print $file "hello there\n";
+ seek $file, 0, 0;
+ my $line = <$file>;
+ $file->close;
+
+It also supports tying via a win32 handle (for example, from C<createFile()>):
+
+ tie FILE, 'Win32API::File', $win32_handle;
+ print FILE "...";
+
+It has not been extensively tested yet and buffered I/O is not yet implemented.
+
+=head2 Exports
+
+Nothing is exported by default. The following tags can be used to
+have large sets of symbols exported: C<":Func">, C<":FuncA">,
+C<":FuncW">, C<":Misc">, C<":DDD_">, C<":DRIVE_">, C<":FILE_">,
+C<":FILE_ATTRIBUTE_">, C<":FILE_FLAG_">, C<":FILE_SHARE_">,
+C<":FILE_TYPE_">, C<":FS_">, C<":FSCTL_">, C<":HANDLE_FLAG_">,
+C<":IOCTL_STORAGE_">, C<":IOCTL_DISK_">, C<":GENERIC_">,
+C<":MEDIA_TYPE">, C<":MOVEFILE_">, C<":SECURITY_">, C<":SEM_">,
+and C<":PARTITION_">.
+
+=over
+
+=item C<":Func">
+
+The basic function names: C<attrLetsToBits>, C<createFile>,
+C<fileConstant>, C<fileLastError>, C<getLogicalDrives>,
+C<setFilePointer>, C<getFileSize>,
+C<CloseHandle>, C<CopyFile>, C<CreateFile>,
+C<DefineDosDevice>, C<DeleteFile>, C<DeviceIoControl>,
+C<FdGetOsFHandle>, C<GetDriveType>, C<GetFileAttributes>,
+C<GetFileSize>, C<GetFileType>, C<GetHandleInformation>,
+C<GetLogicalDrives>, C<GetLogicalDriveStrings>, C<GetOsFHandle>,
+C<GetOverlappedResult>, C<GetVolumeInformation>, C<IsContainerPartition>,
+C<IsRecognizedPartition>, C<MoveFile>, C<MoveFileEx>,
+C<OsFHandleOpen>, C<OsFHandleOpenFd>, C<QueryDosDevice>,
+C<ReadFile>, C<SetErrorMode>, C<SetFilePointer>,
+C<SetHandleInformation>, and C<WriteFile>.
+
+=over
+
+=item attrLetsToBits
+
+=item C<$uBits= attrLetsToBits( $sAttributeLetters )>
+
+Converts a string of file attribute letters into an unsigned value with
+the corresponding bits set. C<$sAttributeLetters> should contain zero
+or more letters from C<"achorst">:
+
+=over
+
+=item C<"a">
+
+C<FILE_ATTRIBUTE_ARCHIVE>
+
+=item C<"c">
+
+C<FILE_ATTRIBUTE_COMPRESSED>
+
+=item C<"h">
+
+C<FILE_ATTRIBUTE_HIDDEN>
+
+=item C<"o">
+
+C<FILE_ATTRIBUTE_OFFLINE>
+
+=item C<"r">
+
+C<FILE_ATTRIBUTE_READONLY>
+
+=item C<"s">
+
+C<FILE_ATTRIBUTE_SYSTEM>
+
+=item C<"t">
+
+C<FILE_ATTRIBUTE_TEMPORARY>
+
+=back
+
+=item createFile
+
+=item C<$hObject= createFile( $sPath )>
+
+=item C<$hObject= createFile( $sPath, $rvhvOptions )>
+
+=item C<$hObject= createFile( $sPath, $svAccess )>
+
+=item C<$hObject= createFile( $sPath, $svAccess, $rvhvOptions )>
+
+=item C<$hObject= createFile( $sPath, $svAccess, $svShare )>
+
+=item C<$hObject= createFile( $sPath, $svAccess, $svShare, $rvhvOptions )>
+
+This is a Perl-friendly wrapper around C<CreateFile>.
+
+On failure, C<$hObject> gets set to a false value and C<regLastError()>
+and C<$^E> are set to the reason for the failure. Otherwise,
+C<$hObject> gets set to a Win32 native file handle which is alwasy
+a true value [returns C<"0 but true"> in the impossible(?) case of
+the handle having a value of C<0>].
+
+C<$sPath> is the path to the file [or device, etc.] to be opened. See
+C<CreateFile> for more information on possible special values for
+C<$sPath>.
+
+C<$svAccess> can be a number containing the bit mask representing
+the specific type(s) of access to the file that you desire. See the
+C<$uAccess> parameter to C<CreateFile> for more information on these
+values.
+
+More likely, C<$svAccess> is a string describing the generic type of
+access you desire and possibly the file creation options to use. In
+this case, C<$svAccess> should contain zero or more characters from
+C<"qrw"> [access desired], zero or one character each from C<"ktn">
+and C<"ce">, and optional white space. These letters stand for,
+respectively, "Query access", "Read access", "Write access", "Keep if
+exists", "Truncate if exists", "New file only", "Create if none", and
+"Existing file only". Case is ignored.
+
+You can pass in C<"?"> for C<$svAccess> to have an error message
+displayed summarizing its possible values. This is very handy when
+doing on-the-fly programming using the Perl debugger:
+
+ Win32API::File::createFile: $svAccess can use the following:
+ One or more of the following:
+ q -- Query access (same as 0)
+ r -- Read access (GENERIC_READ)
+ w -- Write access (GENERIC_WRITE)
+ At most one of the following:
+ k -- Keep if exists
+ t -- Truncate if exists
+ n -- New file only (fail if file already exists)
+ At most one of the following:
+ c -- Create if doesn't exist
+ e -- Existing file only (fail if doesn't exist)
+ '' is the same as 'q k e'
+ 'r' is the same as 'r k e'
+ 'w' is the same as 'w t c'
+ 'rw' is the same as 'rw k c'
+ 'rt' or 'rn' implies 'c'.
+ Or $access can be numeric.
+
+C<$svAccess> is designed to be "do what I mean", so you can skip
+the rest of its explanation unless you are interested in the complex
+details. Note that, if you want write access to a device, you need
+to specify C<"k"> [and perhaps C<"e">, as in C<"w ke"> or C<"rw ke">]
+since Win32 suggests C<OPEN_EXISTING> be used when opening a device.
+
+=over
+
+=item C<"q">
+
+Stands for "Query access". This is really a no-op since you always have
+query access when you open a file. You can specify C<"q"> to document
+that you plan to query the file [or device, etc.]. This is especially
+helpful when you don't want read nor write access since something like
+C<"q"> or C<"q ke"> may be easier to understand than just C<""> or C<"ke">.
+
+=item C<"r">
+
+Stands for "Read access". Sets the C<GENERIC_READ> bit(s) in the
+C<$uAccess> that is passed to C<CreateFile>. This is the default
+access if the C<$svAccess> parameter is missing [or if it is C<undef>
+and C<$rvhvOptions> doesn't specify an C<"Access"> option].
+
+=item C<"w">
+
+Stands for "Write access". Sets the C<GENERIC_WRITE> bit(s) in the
+C<$uAccess> that is passed to C<CreateFile>.
+
+=item C<"k">
+
+Stands for "Keep if exists". If the requested file exists, then it is
+opened. This is the default unless C<GENERIC_WRITE> access has been
+requested but C<GENERIC_READ> access has not been requested. Contrast
+with C<"t"> and C<"n">.
+
+=item C<"t">
+
+Stands for "Truncate if exists". If the requested file exists, then
+it is truncated to zero length and then opened. This is the default if
+C<GENERIC_WRITE> access has been requested and C<GENERIC_READ> access
+has not been requested. Contrast with C<"k"> and C<"n">.
+
+=item C<"n">
+
+Stands for "New file only". If the requested file exists, then it is
+not opened and the C<createFile> call fails. Contrast with C<"k"> and
+C<"t">. Can't be used with C<"e">.
+
+=item C<"c">
+
+Stands for "Create if none". If the requested file does not
+exist, then it is created and then opened. This is the default
+if C<GENERIC_WRITE> access has been requested or if C<"t"> or
+C<"n"> was specified. Contrast with C<"e">.
+
+=item C<"e">
+
+Stands for "Existing file only". If the requested file does not
+exist, then nothing is opened and the C<createFile> call fails. This
+is the default unless C<GENERIC_WRITE> access has been requested or
+C<"t"> or C<"n"> was specified. Contrast with C<"c">. Can't be
+used with C<"n">.
+
+=back
+
+The characters from C<"ktn"> and C<"ce"> are combined to determine the
+what value for C<$uCreate> to pass to C<CreateFile> [unless overridden
+by C<$rvhvOptions>]:
+
+=over
+
+=item C<"kc">
+
+C<OPEN_ALWAYS>
+
+=item C<"ke">
+
+C<OPEN_EXISTING>
+
+=item C<"tc">
+
+C<TRUNCATE_EXISTING>
+
+=item C<"te">
+
+C<CREATE_ALWAYS>
+
+=item C<"nc">
+
+C<CREATE_NEW>
+
+=item C<"ne">
+
+Illegal.
+
+=back
+
+C<$svShare> controls how the file is shared, that is, whether other
+processes can have read, write, and/or delete access to the file while
+we have it opened. C<$svShare> will usually be a string containing zero
+or more characters from C<"rwd"> but can also be a numeric bit mask.
+
+C<"r"> sets the C<FILE_SHARE_READ> bit which allows other processes to have
+read access to the file. C<"w"> sets the C<FILE_SHARE_WRITE> bit which
+allows other processes to have write access to the file. C<"d"> sets the
+C<FILE_SHARE_DELETE> bit which allows other processes to have delete access
+to the file [ignored under Windows 95].
+
+The default for C<$svShare> is C<"rw"> which provides the same sharing as
+using regular perl C<open()>.
+
+If another process currently has read, write, and/or delete access to
+the file and you don't allow that level of sharing, then your call to
+C<createFile> will fail. If you requested read, write, and/or delete
+access and another process already has the file open but doesn't allow
+that level of sharing, then your call to C<createFile> will fail. Once
+you have the file open, if another process tries to open it with read,
+write, and/or delete access and you don't allow that level of sharing,
+then that process won't be allowed to open the file.
+
+C<$rvhvOptions> is a reference to a hash where any keys must be from
+the list C<qw( Access Create Share Attributes Flags Security Model )>.
+The meaning of the value depends on the key name, as described below.
+Any option values in C<$rvhvOptions> override the settings from
+C<$svAccess> and C<$svShare> if they conflict.
+
+=over
+
+=item Flags => $uFlags
+
+C<$uFlags> is an unsigned value having any of the C<FILE_FLAG_*> or
+C<FILE_ATTRIBUTE_*> bits set. Any C<FILE_ATTRIBUTE_*> bits set via the
+C<Attributes> option are logically C<or>ed with these bits. Defaults
+to C<0>.
+
+If opening the client side of a named pipe, then you can also specify
+C<SECURITY_SQOS_PRESENT> along with one of the other C<SECURITY_*>
+constants to specify the security quality of service to be used.
+
+=item Attributes => $sAttributes
+
+A string of zero or more characters from C<"achorst"> [see C<attrLetsToBits>
+for more information] which are converted to C<FILE_ATTRIBUTE_*> bits to
+be set in the C<$uFlags> argument passed to C<CreateFile>.
+
+=item Security => $pSecurityAttributes
+
+C<$pSecurityAttributes> should contain a C<SECURITY_ATTRIBUTES> structure
+packed into a string or C<[]> [the default].
+
+=item Model => $hModelFile
+
+C<$hModelFile> should contain a handle opened with C<GENERIC_READ>
+access to a model file from which file attributes and extended attributes
+are to be copied. Or C<$hModelFile> can be C<0> [the default].
+
+=item Access => $sAccess
+
+=item Access => $uAccess
+
+C<$sAccess> should be a string of zero or more characters from
+C<"qrw"> specifying the type of access desired: "query" or C<0>,
+"read" or C<GENERIC_READ> [the default], or "write" or
+C<GENERIC_WRITE>.
+
+C<$uAccess> should be an unsigned value containing bits set to
+indicate the type of access desired. C<GENERIC_READ> is the default.
+
+=item Create => $sCreate
+
+=item Create => $uCreate
+
+C<$sCreate> should be a string constaing zero or one character from
+C<"ktn"> and zero or one character from C<"ce">. These stand for
+"Keep if exists", "Truncate if exists", "New file only", "Create if
+none", and "Existing file only". These are translated into a
+C<$uCreate> value.
+
+C<$uCreate> should be one of C<OPEN_ALWAYS>, C<OPEN_EXISTING>,
+C<TRUNCATE_EXISTING>, C<CREATE_ALWAYS>, or C<CREATE_NEW>.
+
+=item Share => $sShare
+
+=item Share => $uShare
+
+C<$sShare> should be a string with zero or more characters from
+C<"rwd"> that is translated into a C<$uShare> value. C<"rw"> is
+the default.
+
+C<$uShare> should be an unsigned value having zero or more of the
+following bits set: C<FILE_SHARE_READ>, C<FILE_SHARE_WRITE>, and
+C<FILE_SHARE_DELETE>. C<FILE_SHARE_READ|FILE_SHARE_WRITE> is the
+default.
+
+=back
+
+Examples:
+
+ $hFlop= createFile( "//./A:", "r", "r" )
+ or die "Can't prevent others from writing to floppy: $^E\n";
+ $hDisk= createFile( "//./C:", "rw ke", "" )
+ or die "Can't get exclusive access to C: $^E\n";
+ $hDisk= createFile( $sFilePath, "ke",
+ { Access=>FILE_READ_ATTRIBUTES } )
+ or die "Can't read attributes of $sFilePath: $^E\n";
+ $hTemp= createFile( "$ENV{Temp}/temp.$$", "wn", "",
+ { Attributes=>"hst", Flags=>FILE_FLAG_DELETE_ON_CLOSE() } )
+ or die "Can't create temporary file, temp.$$: $^E\n";
+
+=item getLogicalDrives
+
+=item C<@roots= getLogicalDrives()>
+
+Returns the paths to the root directories of all logical drives
+currently defined. This includes all types of drive lettters, such
+as floppies, CD-ROMs, hard disks, and network shares. A typical
+return value on a poorly equipped computer would be C<("A:\\","C:\\")>.
+
+=item CloseHandle
+
+=item C<CloseHandle( $hObject )>
+
+Closes a Win32 native handle, such as one opened via C<CreateFile>.
+Like most routines, returns a true value if successful and a false
+value [and sets C<$^E> and C<regLastError()>] on failure.
+
+=item CopyFile
+
+=item C<CopyFile( $sOldFileName, $sNewFileName, $bFailIfExists )>
+
+C<$sOldFileName> is the path to the file to be copied.
+C<$sNewFileName> is the path to where the file should be copied.
+Note that you can B<NOT> just specify a path to a directory in
+C<$sNewFileName> to copy the file to that directory using the
+same file name.
+
+If C<$bFailIfExists> is true and C<$sNewFileName> is the path to
+a file that already exists, then C<CopyFile> will fail. If
+C<$bFailIfExists> is falsea, then the copy of the C<$sOldFileNmae>
+file will overwrite the C<$sNewFileName> file if it already exists.
+
+Like most routines, returns a true value if successful and a false
+value [and sets C<$^E> and C<regLastError()>] on failure.
+
+=item CreateFile
+
+=item C<$hObject= CreateFile( $sPath, $uAccess, $uShare, $pSecAttr, $uCreate, $uFlags, $hModel )>
+
+On failure, C<$hObject> gets set to a false value and C<$^E> and
+C<fileLastError()> are set to the reason for the failure. Otherwise,
+C<$hObject> gets set to a Win32 native file handle which is always a
+true value [returns C<"0 but true"> in the impossible(?) case of the
+handle having a value of C<0>].
+
+C<$sPath> is the path to the file [or device, etc.] to be opened.
+
+C<$sPath> can use C<"/"> or C<"\\"> as path delimiters and can even
+mix the two. We will usually only use C<"/"> in our examples since
+using C<"\\"> is usually harder to read.
+
+Under Windows NT, C<$sPath> can start with C<"//?/"> to allow the use
+of paths longer than C<MAX_PATH> [for UNC paths, replace the leading
+C<"//"> with C<"//?/UNC/">, as in C<"//?/UNC/Server/Share/Dir/File.Ext">].
+
+C<$sPath> can start with C<"//./"> to indicate that the rest of the
+path is the name of a "DOS device." You can use C<QueryDosDevice>
+to list all current DOS devices and can add or delete them with
+C<DefineDosDevice>. If you get the source-code distribution of this
+module from CPAN, then it includes an example script, F<ex/ListDevs.plx>
+that will list all current DOS devices and their "native" definition.
+Again, note that this doesn't work under Win95 nor Win98.
+
+The most common such DOS devices include:
+
+=over
+
+=item C<"//./PhysicalDrive0">
+
+Your entire first hard disk. Doesn't work under Windows 95. This
+allows you to read or write raw sectors of your hard disk and to use
+C<DeviceIoControl> to perform miscellaneous queries and operations
+to the hard disk. Writing raw sectors and certain other operations
+can seriously damage your files or the function of your computer.
+
+Locking this for exclusive access [by specifying C<0> for C<$uShare>]
+doesn't prevent access to the partitions on the disk nor their file
+systems. So other processes can still access any raw sectors within
+a partition and can use the file system on the disk as usual.
+
+=item C<"//./C:">
+
+Your F<C:> partition. Doesn't work under Windows 95. This allows
+you to read or write raw sectors of that partition and to use
+C<DeviceIoControl> to perform miscellaneous queries and operations
+to the partition. Writing raw sectors and certain other operations
+can seriously damage your files or the function of your computer.
+
+Locking this for exclusive access doesn't prevent access to the
+physical drive that the partition is on so other processes can
+still access the raw sectors that way. Locking this for exclusive
+access B<does> prevent other processes from opening the same raw
+partition and B<does> prevent access to the file system on it. It
+even prevents the current process from accessing the file system
+on that partition.
+
+=item C<"//./A:">
+
+The raw floppy disk. Doesn't work under Windows 95. This allows
+you to read or write raw sectors of the floppy disk and to use
+C<DeviceIoControl> to perform miscellaneous queries and operations
+to the floopy disk or drive.
+
+Locking this for exclusive access prevents all access to the floppy.
+
+=item C<"//./PIPE/PipeName">
+
+A named pipe, created via C<CreateNamedPipe>.
+
+=back
+
+C<$uAccess> is an unsigned value with bits set indicating the
+type of access desired. Usually either C<0> ["query" access],
+C<GENERIC_READ>, C<GENERIC_WRITE>, C<GENERIC_READ|GENERIC_WRITE>,
+or C<GENERIC_ALL>. More specific types of access can be specified,
+such as C<FILE_APPEND_DATA> or C<FILE_READ_EA>.
+
+C<$uShare> controls how the file is shared, that is, whether other
+processes can have read, write, and/or delete access to the file while
+we have it opened. C<$uShare> is an unsigned value with zero or more
+of these bits set: C<FILE_SHARE_READ>, C<FILE_SHARE_WRITE>, and
+C<FILE_SHARE_DELETE>.
+
+If another process currently has read, write, and/or delete access to
+the file and you don't allow that level of sharing, then your call to
+C<CreateFile> will fail. If you requested read, write, and/or delete
+access and another process already has the file open but doesn't allow
+that level of sharing, thenn your call to C<createFile> will fail. Once
+you have the file open, if another process tries to open it with read,
+write, and/or delete access and you don't allow that level of sharing,
+then that process won't be allowed to open the file.
+
+C<$pSecAttr> should either be C<[]> [for C<NULL>] or a
+C<SECURITY_ATTRIBUTES> data structure packed into a string.
+For example, if C<$pSecDesc> contains a C<SECURITY_DESCRIPTOR>
+structure packed into a string, perhaps via:
+
+ RegGetKeySecurity( $key, 4, $pSecDesc, 1024 );
+
+then you can set C<$pSecAttr> via:
+
+ $pSecAttr= pack( "L P i", 12, $pSecDesc, $bInheritHandle );
+
+C<$uCreate> is one of the following values: C<OPEN_ALWAYS>,
+C<OPEN_EXISTING>, C<TRUNCATE_EXISTING>, C<CREATE_ALWAYS>, and
+C<CREATE_NEW>.
+
+C<$uFlags> is an unsigned value with zero or more bits set indicating
+attributes to associate with the file [C<FILE_ATTRIBUTE_*> values] or
+special options [C<FILE_FLAG_*> values].
+
+If opening the client side of a named pipe, then you can also set
+C<$uFlags> to include C<SECURITY_SQOS_PRESENT> along with one of the
+other C<SECURITY_*> constants to specify the security quality of
+service to be used.
+
+C<$hModel> is C<0> [or C<[]>, both of which mean C<NULL>] or a Win32
+native handle opened with C<GENERIC_READ> access to a model file from
+which file attributes and extended attributes are to be copied if a
+new file gets created.
+
+Examples:
+
+ $hFlop= CreateFile( "//./A:", GENERIC_READ(),
+ FILE_SHARE_READ(), [], OPEN_EXISTING(), 0, [] )
+ or die "Can't prevent others from writing to floppy: $^E\n";
+ $hDisk= CreateFile( $sFilePath, FILE_READ_ATTRIBUTES(),
+ FILE_SHARE_READ()|FILE_SHARE_WRITE(), [], OPEN_EXISTING(), 0, [] )
+ or die "Can't read attributes of $sFilePath: $^E\n";
+ $hTemp= CreateFile( "$ENV{Temp}/temp.$$", GENERIC_WRITE(), 0,
+ CREATE_NEW(), FILE_FLAG_DELETE_ON_CLOSE()|attrLetsToBits("hst"), [] )
+ or die "Can't create temporary file, temp.$$: $^E\n";
+
+=item DefineDosDevice
+
+=item C<DefineDosDevice( $uFlags, $sDosDeviceName, $sTargetPath )>
+
+Defines a new DOS device, overrides the current definition of a DOS
+device, or deletes a definition of a DOS device. Like most routines,
+returns a true value if successful and a false value [and sets C<$^E>
+and C<regLastError()>] on failure.
+
+C<$sDosDeviceName> is the name of a DOS device for which we'd like
+to add or delete a definition.
+
+C<$uFlags> is an unsigned value with zero or more of the following
+bits set:
+
+=over
+
+=item C<DDD_RAW_TARGET_PATH>
+
+Indicates that C<$sTargetPath> will be a raw Windows NT object name.
+This usually means that C<$sTargetPath> starts with C<"\\Device\\">.
+Note that you cannot use C<"/"> in place of C<"\\"> in raw target path
+names.
+
+=item C<DDD_REMOVE_DEFINITION>
+
+Requests that a definition be deleted. If C<$sTargetPath> is
+C<[]> [for C<NULL>], then the most recently added definition for
+C<$sDosDeviceName> is removed. Otherwise the most recently added
+definition matching C<$sTargetPath> is removed.
+
+If the last definition is removed, then the DOS device name is
+also deleted.
+
+=item C<DDD_EXACT_MATCH_ON_REMOVE>
+
+When deleting a definition, this bit causes each C<$sTargetPath> to
+be compared to the full-length definition when searching for the most
+recently added match. If this bit is not set, then C<$sTargetPath>
+only needs to match a prefix of the definition.
+
+=back
+
+C<$sTargetPath> is the DOS device's specific definition that you
+wish to add or delete. For C<DDD_RAW_TARGET_PATH>, these usually
+start with C<"\\Device\\">. If the C<DDD_RAW_TARGET_PATH> bit is
+not set, then C<$sTargetPath> is just an ordinary path to some file
+or directory, providing the functionality of the B<subst> command.
+
+=item DeleteFile
+
+=item C<DeleteFile( $sFileName )>
+
+Deletes the named file. Compared to Perl's C<unlink>, C<DeleteFile>
+has the advantage of not deleting read-only files. For B<some>
+versions of Perl, C<unlink> silently calls C<chmod> whether it needs
+to or not before deleting the file so that files that you have
+protected by marking them as read-only are not always protected from
+Perl's C<unlink>.
+
+Like most routines, returns a true value if successful and a false
+value [and sets C<$^E> and C<regLastError()>] on failure.
+
+=item DeviceIoControl
+
+=item C<DeviceIoControl( $hDevice, $uIoControlCode, $pInBuf, $lInBuf, $opOutBuf, $lOutBuf, $olRetBytes, $pOverlapped )>
+
+Requests a special operation on an I/O [input/output] device, such
+as ejecting a tape or formatting a disk. Like most routines, returns
+a true value if successful and a false value [and sets C<$^E> and
+C<regLastError()>] on failure.
+
+C<$hDevice> is a Win32 native file handle to a device [return value
+from C<CreateFile>].
+
+C<$uIoControlCode> is an unsigned value [a C<IOCTL_*> or C<FSCTL_*>
+constant] indicating the type query or other operation to be performed.
+
+C<$pInBuf> is C<[]> [for C<NULL>] or a data structure packed into a
+string. The type of data structure depends on the C<$uIoControlCode>
+value. C<$lInBuf> is C<0> or the length of the structure in
+C<$pInBuf>. If C<$pInBuf> is not C<[]> and C<$lInBuf> is C<0>, then
+C<$lInBuf> will automatically be set to C<length($pInBuf)> for you.
+
+C<$opOutBuf> is C<[]> [for C<NULL>] or will be set to contain a
+returned data structure packed into a string. C<$lOutBuf> indicates
+how much space to allocate in C<$opOutBuf> for C<DeviceIoControl> to
+store the data structure. If C<$lOutBuf> is a number and C<$opOutBuf>
+already has a buffer allocated for it that is larger than C<$lOutBuf>
+bytes, then this larger buffer size will be passed to C<DeviceIoControl>.
+However, you can force a specific buffer size to be passed to
+C<DeviceIoControl> by prepending a C<"="> to the front of C<$lOutBuf>.
+
+C<$olRetBytes> is C<[]> or is a scalar to receive the number of bytes
+written to C<$opOutBuf>. Even when C<$olRetBytes> is C<[]>, a valid
+pointer to a C<DWORD> [and not C<NULL>] is passed to C<DeviceIoControl>.
+In this case, C<[]> just means that you don't care about the value
+that might be written to C<$olRetBytes>, which is usually the case
+since you can usually use C<length($opOutBuf)> instead.
+
+C<$pOverlapped> is C<[]> or is a C<OVERLAPPED> structure packed into
+a string. This is only useful if C<$hDevice> was opened with the
+C<FILE_FLAG_OVERLAPPED> flag set.
+
+=item FdGetOsFHandle
+
+=item C<$hNativeHandle= FdGetOsFHandle( $ivFd )>
+
+C<FdGetOsFHandle> simply calls C<_get_osfhandle()>. It was renamed
+to better fit in with the rest the function names of this module,
+in particular to distinguish it from C<GetOsFHandle>. It takes an
+integer file descriptor [as from Perl's C<fileno>] and returns the
+Win32 native file handle associated with that file descriptor or
+C<INVALID_HANDLE_VALUE> if C<$ivFd> is not an open file descriptor.
+
+When you call Perl's C<open> to set a Perl file handle [like C<STDOUT>],
+Perl calls C's C<fopen> to set a stdio C<FILE *>. C's C<fopen> calls
+something like Unix's C<open>, that is, Win32's C<_sopen>, to get an
+integer file descriptor [where 0 is for C<STDIN>, 1 for C<STDOUT>, etc.].
+Win32's C<_sopen> calls C<CreateFile> to set a C<HANDLE>, a Win32 native
+file handle. So every Perl file handle [like C<STDOUT>] has an integer
+file descriptor associated with it that you can get via C<fileno>. And,
+under Win32, every file descriptor has a Win32 native file handle
+associated with it. C<FdGetOsFHandle> lets you get access to that.
+
+C<$hNativeHandle> is set to C<INVALID_HANDLE_VALUE> [and
+C<lastFileError()> and C<$^E> are set] if C<FdGetOsFHandle> fails.
+See also C<GetOsFHandle> which provides a friendlier interface.
+
+=item fileConstant
+
+=item C<$value= fileConstant( $sConstantName )>
+
+Fetch the value of a constant. Returns C<undef> if C<$sConstantName>
+is not the name of a constant supported by this module. Never sets
+C<$!> nor C<$^E>.
+
+This function is rarely used since you will usually get the value of a
+constant by having that constant imported into your package by listing
+the constant name in the C<use Win32API::File> statement and then
+simply using the constant name in your code [perhaps followed by
+C<()>]. This function is useful for verifying constant names not in
+Perl code, for example, after prompting a user to type in a constant
+name.
+
+=item fileLastError
+
+=item C<$svError= fileLastError();>
+
+=item C<fileLastError( $uError );>
+
+Returns the last error encountered by a routine from this module.
+It is just like C<$^E> except it isn't changed by anything except
+routines from this module. Ideally you could just use C<$^E>, but
+current versions of Perl often overwrite C<$^E> before you get a
+chance to check it and really old versions of Perl don't really
+support C<$^E> under Win32.
+
+Just like C<$^E>, in a numeric context C<fileLastError()> returns
+the numeric error value while in a string context it returns a
+text description of the error [actually it returns a Perl scalar
+that contains both values so C<$x= fileLastError()> causes C<$x>
+to give different values in string vs. numeric contexts].
+
+The last form sets the error returned by future calls to
+C<fileLastError()> and should not be used often. C<$uError> must
+be a numeric error code. Also returns the dual-valued version
+of C<$uError>.
+
+=item GetDriveType
+
+=item C<$uDriveType= GetDriveType( $sRootPath )>
+
+Takes a string giving the path to the root directory of a file system
+[called a "drive" because every file system is assigned a "drive letter"]
+and returns an unsigned value indicating the type of drive the file
+system is on. The return value should be one of:
+
+=over
+
+=item C<DRIVE_UNKNOWN>
+
+None of the following.
+
+=item C<DRIVE_NO_ROOT_DIR>
+
+A "drive" that does not have a file system. This can be a drive letter
+that hasn't been defined or a drive letter assigned to a partition
+that hasn't been formatted yet.
+
+=item C<DRIVE_REMOVABLE>
+
+A floppy diskette drive or other removable media drive, but not a CD-ROM
+drive.
+
+=item C<DRIVE_FIXED>
+
+An ordinary hard disk partition.
+
+=item C<DRIVE_REMOTE>
+
+A network share.
+
+=item C<DRIVE_CDROM>
+
+A CD-ROM drive.
+
+=item C<DRIVE_RAMDISK>
+
+A "ram disk" or memory-resident virtual file system used for high-speed
+access to small amounts of temporary file space.
+
+=back
+
+=item GetFileAttributes
+
+=item C<$uAttrs = GetFileAttributes( $sPath )>
+
+Takes a path string and returns an unsigned value with attribute flags.
+If it fails, it returns INVALID_FILE_ATTRIBUTES, otherwise it can be
+one or more of the following values:
+
+=over
+
+=item C<FILE_ATTRIBUTE_ARCHIVE>
+
+The file or directory is an archive file or directory. Applications use
+this attribute to mark files for backup or removal.
+
+=item C<FILE_ATTRIBUTE_COMPRESSED>
+
+The file or directory is compressed. For a file, this means that all of
+the data in the file is compressed. For a directory, this means that
+compression is the default for newly created files and subdirectories.
+
+=item C<FILE_ATTRIBUTE_DEVICE>
+
+Reserved; do not use.
+
+=item C<FILE_ATTRIBUTE_DIRECTORY>
+
+The handle identifies a directory.
+
+=item C<FILE_ATTRIBUTE_ENCRYPTED>
+
+The file or directory is encrypted. For a file, this means that all data
+streams in the file are encrypted. For a directory, this means that
+encryption is the default for newly created files and subdirectories.
+
+=item C<FILE_ATTRIBUTE_HIDDEN>
+
+The file or directory is hidden. It is not included in an ordinary directory
+listing.
+
+=item C<FILE_ATTRIBUTE_NORMAL>
+
+The file or directory has no other attributes set. This attribute is valid
+only if used alone.
+
+=item C<FILE_ATTRIBUTE_NOT_CONTENT_INDEXED>
+
+The file will not be indexed by the content indexing service.
+
+=item C<FILE_ATTRIBUTE_OFFLINE>
+
+The data of the file is not immediately available. This attribute indicates
+that the file data has been physically moved to offline storage. This
+attribute is used by Remote Storage, the hierarchical storage management
+software. Applications should not arbitrarily change this attribute.
+
+=item C<FILE_ATTRIBUTE_READONLY>
+
+The file or directory is read-only. Applications can read the file but cannot
+write to it or delete it. In the case of a directory, applications cannot
+delete it.
+
+=item C<FILE_ATTRIBUTE_REPARSE_POINT>
+
+The file or directory has an associated reparse point.
+
+=item C<FILE_ATTRIBUTE_SPARSE_FILE>
+
+The file is a sparse file.
+
+=item C<FILE_ATTRIBUTE_SYSTEM>
+
+The file or directory is part of, or is used exclusively by, the operating
+system.
+
+=item C<FILE_ATTRIBUTE_TEMPORARY>
+
+The file is being used for temporary storage. File systems avoid writing
+data back to mass storage if sufficient cache memory is available, because
+often the application deletes the temporary file shortly after the handle is
+closed. In that case, the system can entirely avoid writing the data.
+Otherwise, the data will be written after the handle is closed.
+
+=back
+
+=item GetFileType
+
+=item C<$uFileType= GetFileType( $hFile )>
+
+Takes a Win32 native file handle and returns a C<FILE_TYPE_*> constant
+indicating the type of the file opened on that handle:
+
+=over
+
+=item C<FILE_TYPE_UNKNOWN>
+
+None of the below. Often a special device.
+
+=item C<FILE_TYPE_DISK>
+
+An ordinary disk file.
+
+=item C<FILE_TYPE_CHAR>
+
+What Unix would call a "character special file", that is, a device that
+works on character streams such as a printer port or a console.
+
+=item C<FILE_TYPE_PIPE>
+
+Either a named or anonymous pipe.
+
+=back
+
+=item getFileSize
+
+=item C<$size= getFileSize( $hFile )>
+
+This is a Perl-friendly wrapper for the C<GetFileSize> (below) API call.
+
+It takes a Win32 native file handle and returns the size in bytes. Since the
+size can be a 64 bit value, on non 64 bit integer Perls the value returned will
+be an object of type C<Math::BigInt>.
+
+=item GetFileSize
+
+=item C<$iSizeLow= GetFileSize($win32Handle, $iSizeHigh)>
+
+Returns the size of a file pointed to by C<$win32Handle>, optionally storing
+the high order 32 bits into C<$iSizeHigh> if it is not C<[]>. If $iSizeHigh is
+C<[]>, a non-zero value indicates success. Otherwise, on failure the return
+value will be C<0xffffffff> and C<fileLastError()> will not be C<NO_ERROR>.
+
+=item GetOverlappedResult
+
+=item C<$bRetval= GetOverlappedResult( $win32Handle, $pOverlapped,
+ $numBytesTransferred, $bWait )>
+
+Used for asynchronous IO in Win32 to get the result of a pending IO operation,
+such as when a file operation returns C<ERROR_IO_PENDING>. Returns a false
+value on failure. The C<$overlapped> structure and C<$numBytesTransferred>
+will be modified with the results of the operation.
+
+As far as creating the C<$pOverlapped> structure, you are currently on your own.
+
+See L<http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dllproc/base/getoverlappedresult.asp> for more information.
+
+=item GetLogicalDrives
+
+=item C<$uDriveBits= GetLogicalDrives()>
+
+Returns an unsigned value with one bit set for each drive letter currently
+defined. If "A:" is currently a valid drive letter, then the C<1> bit
+will be set in C<$uDriveBits>. If "B:" is valid, then the C<2> bit will
+be set. If "Z:" is valid, then the C<2**26> [C<0x4000000>] bit will be
+set.
+
+=item GetLogicalDriveStrings
+
+=item C<$olOutLength= GetLogicalDriveStrings( $lBufSize, $osBuffer )>
+
+For each currently defined drive letter, a C<'\0'>-terminated string
+of the path to the root of its file system is constructed. All of
+these strings are concatenated into a single larger string and an
+extra terminating C<'\0'> is added. This larger string is returned
+in C<$osBuffer>. Note that this includes drive letters that have
+been defined but that have no file system, such as drive letters
+assigned to unformatted partitions.
+
+C<$lBufSize> is the size of the buffer to allocate to store this
+list of strings. C<26*4+1> is always sufficient and should usually
+be used.
+
+C<$osBuffer> is a scalar to be set to contain the constructed string.
+
+C<$olOutLength> is the number of bytes actually written to C<$osBuffer>
+but C<length($osBuffer)> can also be used to determine this.
+
+For example, on a poorly equipped computer,
+
+ GetLogicalDriveStrings( 4*26+1, $osBuffer );
+
+might set C<$osBuffer> to the 9-character string, C<"A:\\\0C:\\\0\0">.
+
+=item GetHandleInformation
+
+=item C<GetHandleInformation( $hObject, $ouFlags )>
+
+Retrieves the flags associated with a Win32 native file handle or object
+handle.
+
+C<$hObject> is an open Win32 native file handle or an open Win32 native
+handle to some other type of object.
+
+C<$ouFlags> will be set to an unsigned value having zero or more of
+the bits C<HANDLE_FLAG_INHERIT> and C<HANDLE_FLAG_PROTECT_FROM_CLOSE>
+set. See the C<":HANDLE_FLAG_"> export class for the meanings of these
+bits.
+
+=item GetOsFHandle
+
+=item C<$hNativeHandle= GetOsFHandle( FILE )>
+
+Takes a Perl file handle [like C<STDIN>] and returns the Win32 native
+file handle associated with it. See C<FdGetOsFHandle> for more
+information about Win32 native file handles.
+
+C<$hNativeHandle> is set to a false value [and C<lastFileError()> and
+C<$^E> are set] if C<GetOsFHandle> fails. C<GetOsFHandle> returns
+C<"0 but true"> in the impossible(?) case of the handle having a value
+of C<0>.
+
+=item GetVolumeInformation
+
+=item C<GetVolumeInformation( $sRootPath, $osVolName, $lVolName, $ouSerialNum, $ouMaxNameLen, $ouFsFlags, $osFsType, $lFsType )>
+
+Gets information about a file system volume, returning a true
+value if successful. On failure, returns a false value and sets
+C<fileLastError()> and C<$^E>.
+
+C<$sRootPath> is a string specifying the path to the root of the file system,
+for example, C<"C:/">.
+
+C<$osVolName> is a scalar to be set to the string representing the
+volume name, also called the file system label. C<$lVolName> is the
+number of bytes to allocate for the C<$osVolName> buffer [see
+L<Buffer Sizes> for more information].
+
+C<$ouSerialNum> is C<[]> [for C<NULL>] or will be set to the numeric
+value of the volume's serial number.
+
+C<$ouMaxNameLen> is C<[]> [for C<NULL>] or will be set to the maximum
+length allowed for a file name or directory name within the file system.
+
+C<$osFsType> is a scalar to be set to the string representing the
+file system type, such as C<"FAT"> or C<"NTFS">. C<$lFsType> is the
+number of bytes to allocate for the C<$osFsType> buffer [see
+L<Buffer Sizes> for more information].
+
+C<$ouFsFlags> is C<[]> [for C<NULL>] or will be set to an unsigned integer
+with bits set indicating properties of the file system:
+
+=over
+
+=item C<FS_CASE_IS_PRESERVED>
+
+The file system preserves the case of file names [usually true].
+That is, it doesn't change the case of file names such as forcing
+them to upper- or lower-case.
+
+=item C<FS_CASE_SENSITIVE>
+
+The file system supports the ability to not ignore the case of file
+names [but might ignore case the way you are using it]. That is, the
+file system has the ability to force you to get the letter case of a
+file's name exactly right to be able to open it. This is true for
+"NTFS" file systems, even though case in file names is usually still
+ignored.
+
+=item C<FS_UNICODE_STORED_ON_DISK>
+
+The file system preserves Unicode in file names [true for "NTFS"].
+
+=item C<FS_PERSISTENT_ACLS>
+
+The file system supports setting Access Control Lists on files [true
+for "NTFS"].
+
+=item C<FS_FILE_COMPRESSION>
+
+The file system supports compression on a per-file basis [true for
+"NTFS"].
+
+=item C<FS_VOL_IS_COMPRESSED>
+
+The entire file system is compressed such as via "DoubleSpace".
+
+=back
+
+=item IsRecognizedPartition
+
+=item C<IsRecognizedPartition( $ivPartitionType )>
+
+Takes a partition type and returns whether that partition type is
+supported under Win32. C<$ivPartitonType> is an integer value as from
+the operating system byte of a hard disk's DOS-compatible partition
+table [that is, a partition table for x86-based Win32, not, for
+example, one used with Windows NT for Alpha processors]. For example,
+the C<PartitionType> member of the C<PARTITION_INFORMATION> structure.
+
+Common values for C<$ivPartitionType> include C<PARTITION_FAT_12==1>,
+C<PARTITION_FAT_16==4>, C<PARTITION_EXTENDED==5>, C<PARTITION_FAT32==0xB>.
+
+=item IsContainerPartition
+
+=item C<IsContainerPartition( $ivPartitionType )>
+
+Takes a partition type and returns whether that partition is a
+"container" partition that is supported under Win32, that is, whether
+it is an "extended" partition that can contain "logical" partitions.
+C<$ivPartitonType> is as for C<IsRecognizedPartition>.
+
+=item MoveFile
+
+=item C<MoveFile( $sOldName, $sNewName )>
+
+Renames a file or directory. C<$sOldName> is the name of the existing
+file or directory that is to be renamed. C<$sNewName> is the new name
+to give the file or directory. Returns a true value if the move
+succeeds. For failure, returns a false value and sets
+C<fileLastErorr()> and C<$^E> to the reason for the failure.
+
+Files can be "renamed" between file systems and the file contents and
+some attributes will be moved. Directories can only be renamed within
+one file system. If there is already a file or directory named
+C<$sNewName>, then C<MoveFile> will fail.
+
+=item MoveFileEx
+
+=item C<MoveFileEx( $sOldName, $sNewName, $uFlags )>
+
+Renames a file or directory. C<$sOldName> is the name of the existing
+file or directory that is to be renamed. C<$sNewName> is the new name
+to give the file or directory. Returns a true value if the move
+succeeds. For failure, returns a false value and sets
+C<fileLastErorr()> and C<$^E> to the reason for the failure.
+
+C<$uFlags> is an unsigned value with zero or more of the following bits set:
+
+=over
+
+=item C<MOVEFILE_REPLACE_EXISTING>
+
+If this bit is set and a file [but not a directory] named C<$sNewName>
+already exists, then it will be replaced by C<$sOldName>. If this bit
+is not set then C<MoveFileEx> will fail rather than replace an existing
+C<$sNewName>.
+
+=item C<MOVEFILE_COPY_ALLOWED>
+
+Allows files [but not directories] to be moved between file systems
+by copying the C<$sOldName> file data and some attributes to
+C<$sNewName> and then deleting C<$sOldName>. If this bit is not set
+[or if C<$sOldName> denotes a directory] and C<$sNewName> refers to a
+different file system than C<$sOldName>, then C<MoveFileEx> will fail.
+
+=item C<MOVEFILE_DELAY_UNTIL_REBOOT>
+
+Preliminary verifications are made and then an entry is added to the
+Registry to cause the rename [or delete] operation to be done the
+next time this copy of the operating system is booted [right after
+any automatic file system checks have completed]. This is not
+supported under Windows 95.
+
+When this bit is set, C<$sNewName> can be C<[]> [for C<NULL>] to
+indicate that C<$sOldName> should be deleted during the next boot
+rather than renamed.
+
+Setting both the C<MOVEFILE_COPY_ALLOWED> and
+C<MOVEFILE_DELAY_UNTIL_REBOOT> bits will cause C<MoveFileEx> to fail.
+
+=item C<MOVEFILE_WRITE_THROUGH>
+
+Ensures that C<MoveFileEx> won't return until the operation has
+finished and been flushed to disk. This is not supported under
+Windows 95. Only affects file renames to another file system,
+forcing a buffer flush at the end of the copy operation.
+
+=back
+
+=item OsFHandleOpen
+
+=item C<OsFHandleOpen( FILE, $hNativeHandle, $sMode )>
+
+Opens a Perl file handle based on an already open Win32 native
+file handle [much like C's C<fdopen()> does with a file descriptor].
+Returns a true value if the open operation succeeded. For failure,
+returns a false value and sets C<$!> [and possibly C<fileLastError()>
+and C<$^E>] to the reason for the failure.
+
+C<FILE> is a Perl file handle [in any of the supported forms, a
+bareword, a string, a typeglob, or a reference to a typeglob] that
+will be opened. If C<FILE> is already open, it will automatically
+be closed before it is reopened.
+
+C<$hNativeHandle> is an open Win32 native file handle, probably the
+return value from C<CreateFile> or C<createFile>.
+
+C<$sMode> is string of zero or more letters from C<"rwatb">. These
+are translated into a combination C<O_RDONLY> [C<"r">], C<O_WRONLY>
+[C<"w">], C<O_RDWR> [C<"rw">], C<O_APPEND> [C<"a">], C<O_TEXT>
+[C<"t">], and C<O_BINARY> [C<"b">] flags [see the L<Fcntl> module]
+that is passed to C<OsFHandleOpenFd>. Currently only C<O_APPEND>
+and C<O_TEXT> have any significance.
+
+Also, a C<"r"> and/or C<"w"> in C<$sMode> is used to decide how the
+file descriptor is converted into a Perl file handle, even though this
+doesn't appear to make a difference. One of the following is used:
+
+ open( FILE, "<&=".$ivFd ) # "r" w/o "w"
+ open( FILE, ">&=".$ivFd ) # "w" w/o "r"
+ open( FILE, "+<&=".$ivFd ) # both "r" and "w"
+
+C<OsFHandleOpen> eventually calls the Win32-specific C routine
+C<_open_osfhandle()> or Perl's "improved" version called
+C<win32_open_osfhandle()>. Prior to Perl5.005, C's
+C<_open_osfhandle()> is called which will fail if
+C<GetFileType($hNativeHandle)> would return C<FILE_TYPE_UNKNOWN>. For
+Perl5.005 and later, C<OsFHandleOpen> calls C<win32_open_osfhandle()>
+from the Perl DLL which doesn't have this restriction.
+
+=item OsFHandleOpenFd
+
+=item C<$ivFD= OsFHandleOpenFd( $hNativeHandle, $uMode )>
+
+Opens a file descriptor [C<$ivFD>] based on an already open Win32
+native file handle, C<$hNativeHandle>. This just calls the
+Win32-specific C routine C<_open_osfhandle()> or Perl's "improved"
+version called C<win32_open_osfhandle()>. Prior to Perl5.005 and in Cygwin
+Perl, C's C<_open_osfhandle()> is called which will fail if
+C<GetFileType($hNativeHandle)> would return C<FILE_TYPE_UNKNOWN>. For
+Perl5.005 and later, C<OsFHandleOpenFd> calls C<win32_open_osfhandle()> from
+the Perl DLL which doesn't have this restriction.
+
+C<$uMode> the logical combination of zero or more C<O_*> constants
+exported by the C<Fcntl> module. Currently only C<O_APPEND> and
+C<O_TEXT> have any significance.
+
+C<$ivFD> will be non-negative if the open operation was successful.
+For failure, C<-1> is returned and C<$!> [and possibly
+C<fileLastError()> and C<$^E>] is set to the reason for the failure.
+
+=item QueryDosDevice
+
+=item C<$olTargetLen= QueryDosDevice( $sDosDeviceName, $osTargetPath, $lTargetBuf )>
+
+Looks up the definition of a given "DOS" device name, yielding the
+active Windows NT native device name along with any currently dormant
+definitions.
+
+C<$sDosDeviceName> is the name of the "DOS" device whose definitions
+we want. For example, C<"C:">, C<"COM1">, or C<"PhysicalDrive0">.
+If C<$sDosDeviceName> is C<[]> [for C<NULL>], the list of all DOS
+device names is returned instead.
+
+C<$osTargetPath> will be assigned a string containing the list of
+definitions. The definitions are each C<'\0'>-terminate and are
+concatenated into the string, most recent first, with an extra C<'\0'>
+at the end of the whole string [see C<GetLogicalDriveStrings> for
+a sample of this format].
+
+C<$lTargetBuf> is the size [in bytes] of the buffer to allocate for
+C<$osTargetPath>. See L<Buffer Sizes> for more information.
+
+C<$olTargetLen> is set to the number of bytes written to
+C<$osTargetPath> but you can also use C<length($osTargetPath)>
+to determine this.
+
+For failure, C<0> is returned and C<fileLastError()> and C<$^E> are
+set to the reason for the failure.
+
+=item ReadFile
+
+=item C<ReadFile( $hFile, $opBuffer, $lBytes, $olBytesRead, $pOverlapped )>
+
+Reads bytes from a file or file-like device. Returns a true value if
+the read operation was successful. For failure, returns a false value
+and sets C<fileLastError()> and C<$^E> for the reason for the failure.
+
+C<$hFile> is a Win32 native file handle that is already open to the
+file or device to read from.
+
+C<$opBuffer> will be set to a string containing the bytes read.
+
+C<$lBytes> is the number of bytes you would like to read.
+C<$opBuffer> is automatically initialized to have a buffer large
+enough to hold that many bytes. Unlike other buffer sizes, C<$lBytes>
+does not need to have a C<"="> prepended to it to prevent a larger
+value to be passed to the underlying Win32 C<ReadFile> API. However,
+a leading C<"="> will be silently ignored, even if Perl warnings are
+enabled.
+
+If C<$olBytesRead> is not C<[]>, it will be set to the actual number
+of bytes read, though C<length($opBuffer)> can also be used to
+determine this.
+
+C<$pOverlapped> is C<[]> or is a C<OVERLAPPED> structure packed
+into a string. This is only useful if C<$hFile> was opened with
+the C<FILE_FLAG_OVERLAPPED> flag set.
+
+=item SetErrorMode
+
+=item C<$uOldMode= SetErrorMode( $uNewMode )>
+
+Sets the mode controlling system error handling B<and> returns the
+previous mode value. Both C<$uOldMode> and C<$uNewMode> will have
+zero or more of the following bits set:
+
+=over
+
+=item C<SEM_FAILCRITICALERRORS>
+
+If set, indicates that when a critical error is encountered, the call
+that triggered the error fails immediately. Normally this bit is not
+set, which means that a critical error causes a dialogue box to appear
+notifying the desktop user that some application has triggered a
+critical error. The dialogue box allows the desktop user to decide
+whether the critical error is returned to the process, is ignored, or
+the offending operation is retried.
+
+This affects the C<CreateFile> and C<GetVolumeInformation> calls.
+
+Setting this bit is useful for allowing you to check whether a floppy
+diskette is in the floppy drive.
+
+=item C<SEM_NOALIGNMENTFAULTEXCEPT>
+
+If set, this causes memory access misalignment faults to be
+automatically fixed in a manner invisible to the process. This flag
+is ignored on x86-based versions of Windows NT. This flag is not
+supported on Windows 95.
+
+=item C<SEM_NOGPFAULTERRORBOX>
+
+If set, general protection faults do not generate a dialogue box but
+can instead be handled by the process via an exception handler. This
+bit should not be set by programs that don't know how to handle such
+faults.
+
+=item C<SEM_NOOPENFILEERRORBOX>
+
+If set, then when an attempt to continue reading from or writing to
+an already open file [usually on a removable medium like a floppy
+diskette] finds the file no longer available, the call will
+immediately fail. Normally this bit is not set, which means that
+instead a dialogue box will appear notifying the desktop user that
+some application has run into this problem. The dialogue box allows
+the desktop user to decide whether the failure is returned to the
+process, is ignored, or the offending operation is retried.
+
+This affects the C<ReadFile> and C<WriteFile> calls.
+
+=back
+
+=item setFilePointer
+
+=item C<$uNewPos = setFilePointer( $hFile, $ivOffset, $uFromWhere )>
+
+This is a perl-friendly wrapper for the SetFilePointer API (below).
+C<$ivOffset> can be a 64 bit integer or C<Math::BigInt> object if your Perl
+doesn't have 64 bit integers. The return value is the new offset and will
+likewise be a 64 bit integer or a C<Math::BigInt> object.
+
+=item SetFilePointer
+
+=item C<$uNewPos = SetFilePointer( $hFile, $ivOffset, $ioivOffsetHigh, $uFromWhere )>
+
+The native Win32 version of C<seek()>. C<SetFilePointer> sets the
+position within a file where the next read or write operation will
+start from.
+
+C<$hFile> is a Win32 native file handle.
+
+C<$uFromWhere> is either C<FILE_BEGIN>, C<FILE_CURRENT>, or
+C<FILE_END>, indicating that the new file position is being specified
+relative to the beginning of the file, the current file pointer, or
+the end of the file, respectively.
+
+C<$ivOffset> is [if C<$ioivOffsetHigh> is C<[]>] the offset [in bytes]
+to the new file position from the position specified via
+C<$uFromWhere>. If C<$ioivOffsetHigh> is not C<[]>, then C<$ivOffset>
+is converted to an unsigned value to be used as the low-order 4 bytes
+of the offset.
+
+C<$ioivOffsetHigh> can be C<[]> [for C<NULL>] to indicate that you are
+only specifying a 4-byte offset and the resulting file position will
+be 0xFFFFFFFE or less [just under 4GB]. Otherwise C<$ioivOfffsetHigh>
+starts out with the high-order 4 bytes [signed] of the offset and gets
+set to the [unsigned] high-order 4 bytes of the resulting file position.
+
+The underlying C<SetFilePointer> returns C<0xFFFFFFFF> to indicate
+failure, but if C<$ioivOffsetHigh> is not C<[]>, you would also have
+to check C<$^E> to determine whether C<0xFFFFFFFF> indicates an error
+or not. C<Win32API::File::SetFilePointer> does this checking for you
+and returns a false value if and only if the underlying
+C<SetFilePointer> failed. For this reason, C<$uNewPos> is set to
+C<"0 but true"> if you set the file pointer to the beginning of the
+file [or any position with 0 for the low-order 4 bytes].
+
+So the return value will be true if the seek operation was successful.
+For failure, a false value is returned and C<fileLastError()> and
+C<$^E> are set to the reason for the failure.
+
+=item SetHandleInformation
+
+=item C<SetHandleInformation( $hObject, $uMask, $uFlags )>
+
+Sets the flags associated with a Win32 native file handle or object
+handle. Returns a true value if the operation was successful. For
+failure, returns a false value and sets C<fileLastError()> and C<$^E>
+for the reason for the failure.
+
+C<$hObject> is an open Win32 native file handle or an open Win32 native
+handle to some other type of object.
+
+C<$uMask> is an unsigned value having one or more of the bits
+C<HANDLE_FLAG_INHERIT> and C<HANDLE_FLAG_PROTECT_FROM_CLOSE> set.
+Only bits set in C<$uMask> will be modified by C<SetHandleInformation>.
+
+C<$uFlags> is an unsigned value having zero or more of the bits
+C<HANDLE_FLAG_INHERIT> and C<HANDLE_FLAG_PROTECT_FROM_CLOSE> set.
+For each bit set in C<$uMask>, the cooresponding bit in the handle's
+flags is set to the value of the cooresponding bit in C<$uFlags>.
+
+If C<$uOldFlags> were the value of the handle's flags before the
+call to C<SetHandleInformation>, then the value of the handle's
+flags afterward would be:
+
+ ( $uOldFlags & ~$uMask ) | ( $uFlags & $uMask )
+
+[at least as far as the C<HANDLE_FLAG_INHERIT> and
+C<HANDLE_FLAG_PROTECT_FROM_CLOSE> bits are concerned.]
+
+See the C<":HANDLE_FLAG_"> export class for the meanings of these bits.
+
+=item WriteFile
+
+=item C<WriteFile( $hFile, $pBuffer, $lBytes, $ouBytesWritten, $pOverlapped )>
+
+Write bytes to a file or file-like device. Returns a true value if
+the operation was successful. For failure, returns a false value and
+sets C<fileLastError()> and C<$^E> for the reason for the failure.
+
+C<$hFile> is a Win32 native file handle that is already open to the
+file or device to be written to.
+
+C<$pBuffer> is a string containing the bytes to be written.
+
+C<$lBytes> is the number of bytes you would like to write. If
+C<$pBuffer> is not at least C<$lBytes> long, C<WriteFile> croaks. You
+can specify C<0> for C<$lBytes> to write C<length($pBuffer)> bytes.
+A leading C<"="> on C<$lBytes> will be silently ignored, even if Perl
+warnings are enabled.
+
+C<$ouBytesWritten> will be set to the actual number of bytes written
+unless you specify it as C<[]>.
+
+C<$pOverlapped> is C<[]> or is an C<OVERLAPPED> structure packed
+into a string. This is only useful if C<$hFile> was opened with
+the C<FILE_FLAG_OVERLAPPED> flag set.
+
+=back
+
+=item C<":FuncA">
+
+The ASCII-specific functions. Each of these is just the same as the
+version without the trailing "A".
+
+ CopyFileA
+ CreateFileA
+ DefineDosDeviceA
+ DeleteFileA
+ GetDriveTypeA
+ GetFileAttributesA
+ GetLogicalDriveStringsA
+ GetVolumeInformationA
+ MoveFileA
+ MoveFileExA
+ QueryDosDeviceA
+
+=item C<":FuncW">
+
+The wide-character-specific (Unicode) functions. Each of these is
+just the same as the version without the trailing "W" except that
+strings are expected in Unicode and some lengths are measured as
+number of C<WCHAR>s instead of number of bytes, as indicated below.
+
+=over
+
+=item CopyFileW
+
+=item C<CopyFileW( $swOldFileName, $swNewFileName, $bFailIfExists )>
+
+C<$swOldFileName> and C<$swNewFileName> are Unicode strings.
+
+=item CreateFileW
+
+=item C<$hObject= CreateFileW( $swPath, $uAccess, $uShare, $pSecAttr, $uCreate, $uFlags, $hModel )>
+
+C<$swPath> is Unicode.
+
+=item DefineDosDeviceW
+
+=item C<DefineDosDeviceW( $uFlags, $swDosDeviceName, $swTargetPath )>
+
+C<$swDosDeviceName> and C<$swTargetPath> are Unicode.
+
+=item DeleteFileW
+
+=item C<DeleteFileW( $swFileName )>
+
+C<$swFileName> is Unicode.
+
+=item GetDriveTypeW
+
+=item C<$uDriveType= GetDriveTypeW( $swRootPath )>
+
+C<$swRootPath> is Unicode.
+
+=item GetFileAttributesW
+
+=item C<$uAttrs= GetFileAttributesW( $swPath )>
+
+C<$swPath> is Unicode.
+
+=item GetLogicalDriveStringsW
+
+=item C<$olwOutLength= GetLogicalDriveStringsW( $lwBufSize, $oswBuffer )>
+
+Unicode is stored in C<$oswBuffer>. C<$lwBufSize> and C<$olwOutLength>
+are measured as number of C<WCHAR>s.
+
+=item GetVolumeInformationW
+
+=item C<GetVolumeInformationW( $swRootPath, $oswVolName, $lwVolName, $ouSerialNum, $ouMaxNameLen, $ouFsFlags, $oswFsType, $lwFsType )>
+
+C<$swRootPath> is Unicode and Unicode is written to C<$oswVolName> and
+C<$oswFsType>. C<$lwVolName> and C<$lwFsType> are measures as number
+of C<WCHAR>s.
+
+=item MoveFileW
+
+=item C<MoveFileW( $swOldName, $swNewName )>
+
+C<$swOldName> and C<$swNewName> are Unicode.
+
+=item MoveFileExW
+
+=item C<MoveFileExW( $swOldName, $swNewName, $uFlags )>
+
+C<$swOldName> and C<$swNewName> are Unicode.
+
+=item QueryDosDeviceW
+
+=item C<$olwTargetLen= QueryDosDeviceW( $swDeviceName, $oswTargetPath, $lwTargetBuf )>
+
+C<$swDeviceName> is Unicode and Unicode is written to
+C<$oswTargetPath>. C<$lwTargetBuf> and C<$olwTargetLen> are measured
+as number of C<WCHAR>s.
+
+=back
+
+=item C<":Misc">
+
+Miscellaneous constants. Used for the C<$uCreate> argument of
+C<CreateFile> or the C<$uFromWhere> argument of C<SetFilePointer>.
+Plus C<INVALID_HANDLE_VALUE>, which you usually won't need to check
+for since most routines translate it into a false value.
+
+ CREATE_ALWAYS CREATE_NEW OPEN_ALWAYS
+ OPEN_EXISTING TRUNCATE_EXISTING INVALID_HANDLE_VALUE
+ FILE_BEGIN FILE_CURRENT FILE_END
+
+=item C<":DDD_">
+
+Constants for the C<$uFlags> argument of C<DefineDosDevice>.
+
+ DDD_EXACT_MATCH_ON_REMOVE
+ DDD_RAW_TARGET_PATH
+ DDD_REMOVE_DEFINITION
+
+=item C<":DRIVE_">
+
+Constants returned by C<GetDriveType>.
+
+ DRIVE_UNKNOWN DRIVE_NO_ROOT_DIR DRIVE_REMOVABLE
+ DRIVE_FIXED DRIVE_REMOTE DRIVE_CDROM
+ DRIVE_RAMDISK
+
+=item C<":FILE_">
+
+Specific types of access to files that can be requested via the
+C<$uAccess> argument to C<CreateFile>.
+
+ FILE_READ_DATA FILE_LIST_DIRECTORY
+ FILE_WRITE_DATA FILE_ADD_FILE
+ FILE_APPEND_DATA FILE_ADD_SUBDIRECTORY
+ FILE_CREATE_PIPE_INSTANCE FILE_READ_EA
+ FILE_WRITE_EA FILE_EXECUTE
+ FILE_TRAVERSE FILE_DELETE_CHILD
+ FILE_READ_ATTRIBUTES FILE_WRITE_ATTRIBUTES
+ FILE_ALL_ACCESS FILE_GENERIC_READ
+ FILE_GENERIC_WRITE FILE_GENERIC_EXECUTE )],
+
+=item C<":FILE_ATTRIBUTE_">
+
+File attribute constants. Returned by C<attrLetsToBits> and used in
+the C<$uFlags> argument to C<CreateFile>.
+
+ FILE_ATTRIBUTE_ARCHIVE FILE_ATTRIBUTE_COMPRESSED
+ FILE_ATTRIBUTE_HIDDEN FILE_ATTRIBUTE_NORMAL
+ FILE_ATTRIBUTE_OFFLINE FILE_ATTRIBUTE_READONLY
+ FILE_ATTRIBUTE_SYSTEM FILE_ATTRIBUTE_TEMPORARY
+
+In addition, C<GetFileAttributes> can return these constants (or
+INVALID_FILE_ATTRIBUTES in case of an error).
+
+ FILE_ATTRIBUTE_DEVICE FILE_ATTRIBUTE_DIRECTORY
+ FILE_ATTRIBUTE_ENCRYPTED FILE_ATTRIBUTE_NOT_CONTENT_INDEXED
+ FILE_ATTRIBUTE_REPARSE_POINT FILE_ATTRIBUTE_SPARSE_FILE
+
+=item C<":FILE_FLAG_">
+
+File option flag constants. Used in the C<$uFlags> argument to
+C<CreateFile>.
+
+ FILE_FLAG_BACKUP_SEMANTICS FILE_FLAG_DELETE_ON_CLOSE
+ FILE_FLAG_NO_BUFFERING FILE_FLAG_OVERLAPPED
+ FILE_FLAG_POSIX_SEMANTICS FILE_FLAG_RANDOM_ACCESS
+ FILE_FLAG_SEQUENTIAL_SCAN FILE_FLAG_WRITE_THROUGH
+ FILE_FLAG_OPEN_REPARSE_POINT
+
+=item C<":FILE_SHARE_">
+
+File sharing constants. Used in the C<$uShare> argument to
+C<CreateFile>.
+
+ FILE_SHARE_DELETE FILE_SHARE_READ FILE_SHARE_WRITE
+
+=item C<":FILE_TYPE_">
+
+File type constants. Returned by C<GetFileType>.
+
+ FILE_TYPE_CHAR FILE_TYPE_DISK
+ FILE_TYPE_PIPE FILE_TYPE_UNKNOWN
+
+=item C<":FS_">
+
+File system characteristics constants. Placed in the C<$ouFsFlags>
+argument to C<GetVolumeInformation>.
+
+ FS_CASE_IS_PRESERVED FS_CASE_SENSITIVE
+ FS_UNICODE_STORED_ON_DISK FS_PERSISTENT_ACLS
+ FS_FILE_COMPRESSION FS_VOL_IS_COMPRESSED
+
+=item C<":HANDLE_FLAG_">
+
+Flag bits modifying the behavior of an object handle and accessed via
+C<GetHandleInformation> and C<SetHandleInformation>.
+
+=over
+
+=item HANDLE_FLAG_INHERIT
+
+If this bit is set, then children of this process who inherit handles
+[that is, processes created by calls to the Win32 C<CreateProcess> API
+with the C<bInheritHandles> parameter specified as C<TRUE>], will inherit
+this particular object handle.
+
+=item HANDLE_FLAG_PROTECT_FROM_CLOSE
+
+If this bit is set, then calls to C<CloseHandle> against this handle
+will be ignored, leaving the handle open and usable.
+
+=back
+
+=item C<":IOCTL_STORAGE_">
+
+I/O control operations for generic storage devices. Used in the
+C<$uIoControlCode> argument to C<DeviceIoControl>. Includes
+C<IOCTL_STORAGE_CHECK_VERIFY>, C<IOCTL_STORAGE_MEDIA_REMOVAL>,
+C<IOCTL_STORAGE_EJECT_MEDIA>, C<IOCTL_STORAGE_LOAD_MEDIA>,
+C<IOCTL_STORAGE_RESERVE>, C<IOCTL_STORAGE_RELEASE>,
+C<IOCTL_STORAGE_FIND_NEW_DEVICES>, and
+C<IOCTL_STORAGE_GET_MEDIA_TYPES>.
+
+=over
+
+=item C<IOCTL_STORAGE_CHECK_VERIFY>
+
+Verify that a device's media is accessible. C<$pInBuf> and C<$opOutBuf>
+should both be C<[]>. If C<DeviceIoControl> returns a true value, then
+the media is currently accessible.
+
+=item C<IOCTL_STORAGE_MEDIA_REMOVAL>
+
+Allows the device's media to be locked or unlocked. C<$opOutBuf> should
+be C<[]>. C<$pInBuf> should be a C<PREVENT_MEDIA_REMOVAL> data structure,
+which is simply an interger containing a boolean value:
+
+ $pInBuf= pack( "i", $bPreventMediaRemoval );
+
+=item C<IOCTL_STORAGE_EJECT_MEDIA>
+
+Requests that the device eject the media. C<$pInBuf> and C<$opOutBuf>
+should both be C<[]>.
+
+=item C<IOCTL_STORAGE_LOAD_MEDIA>
+
+Requests that the device load the media. C<$pInBuf> and C<$opOutBuf>
+should both be C<[]>.
+
+=item C<IOCTL_STORAGE_RESERVE>
+
+Requests that the device be reserved. C<$pInBuf> and C<$opOutBuf>
+should both be C<[]>.
+
+=item C<IOCTL_STORAGE_RELEASE>
+
+Releases a previous device reservation. C<$pInBuf> and C<$opOutBuf>
+should both be C<[]>.
+
+=item C<IOCTL_STORAGE_FIND_NEW_DEVICES>
+
+No documentation on this IOCTL operation was found.
+
+=item C<IOCTL_STORAGE_GET_MEDIA_TYPES>
+
+Requests information about the type of media supported by the device.
+C<$pInBuf> should be C<[]>. C<$opOutBuf> will be set to contain a
+vector of C<DISK_GEOMETRY> data structures, which can be decoded via:
+
+ # Calculate the number of DISK_GEOMETRY structures returned:
+ my $cStructs= length($opOutBuf)/(4+4+4+4+4+4);
+ my @fields= unpack( "L l I L L L" x $cStructs, $opOutBuf )
+ my( @ucCylsLow, @ivcCylsHigh, @uMediaType, @uTracksPerCyl,
+ @uSectsPerTrack, @uBytesPerSect )= ();
+ while( @fields ) {
+ push( @ucCylsLow, unshift @fields );
+ push( @ivcCylsHigh, unshift @fields );
+ push( @uMediaType, unshift @fields );
+ push( @uTracksPerCyl, unshift @fields );
+ push( @uSectsPerTrack, unshift @fields );
+ push( @uBytesPerSect, unshift @fields );
+ }
+
+For the C<$i>th type of supported media, the following variables will
+contain the following data.
+
+=over
+
+=item C<$ucCylsLow[$i]>
+
+The low-order 4 bytes of the total number of cylinders.
+
+=item C<$ivcCylsHigh[$i]>
+
+The high-order 4 bytes of the total number of cylinders.
+
+=item C<$uMediaType[$i]>
+
+A code for the type of media. See the C<":MEDIA_TYPE"> export class.
+
+=item C<$uTracksPerCyl[$i]>
+
+The number of tracks in each cylinder.
+
+=item C<$uSectsPerTrack[$i]>
+
+The number of sectors in each track.
+
+=item C<$uBytesPerSect[$i]>
+
+The number of bytes in each sector.
+
+=back
+
+=back
+
+=item C<":IOCTL_DISK_">
+
+I/O control operations for disk devices. Used in the C<$uIoControlCode>
+argument to C<DeviceIoControl>. Most of these are to be used on
+physical drive devices like C<"//./PhysicalDrive0">. However,
+C<IOCTL_DISK_GET_PARTITION_INFO> and C<IOCTL_DISK_SET_PARTITION_INFO>
+should only be used on a single-partition device like C<"//./C:">. Also,
+C<IOCTL_DISK_GET_MEDIA_TYPES> is documented as having been superceded but
+is still useful when used on a floppy device like C<"//./A:">.
+
+Includes C<IOCTL_DISK_FORMAT_TRACKS>, C<IOCTL_DISK_FORMAT_TRACKS_EX>,
+C<IOCTL_DISK_GET_DRIVE_GEOMETRY>, C<IOCTL_DISK_GET_DRIVE_LAYOUT>,
+C<IOCTL_DISK_GET_MEDIA_TYPES>, C<IOCTL_DISK_GET_PARTITION_INFO>,
+C<IOCTL_DISK_HISTOGRAM_DATA>, C<IOCTL_DISK_HISTOGRAM_RESET>,
+C<IOCTL_DISK_HISTOGRAM_STRUCTURE>, C<IOCTL_DISK_IS_WRITABLE>,
+C<IOCTL_DISK_LOGGING>, C<IOCTL_DISK_PERFORMANCE>,
+C<IOCTL_DISK_REASSIGN_BLOCKS>, C<IOCTL_DISK_REQUEST_DATA>,
+C<IOCTL_DISK_REQUEST_STRUCTURE>, C<IOCTL_DISK_SET_DRIVE_LAYOUT>,
+C<IOCTL_DISK_SET_PARTITION_INFO>, and C<IOCTL_DISK_VERIFY>.
+
+=over
+
+=item C<IOCTL_DISK_GET_DRIVE_GEOMETRY>
+
+Request information about the size and geometry of the disk. C<$pInBuf>
+should be C<[]>. C<$opOutBuf> will be set to a C<DISK_GEOMETRY> data
+structure which can be decode via:
+
+ ( $ucCylsLow, $ivcCylsHigh, $uMediaType, $uTracksPerCyl,
+ $uSectsPerTrack, $uBytesPerSect )= unpack( "L l I L L L", $opOutBuf );
+
+=over
+
+=item C<$ucCylsLow>
+
+The low-order 4 bytes of the total number of cylinders.
+
+=item C<$ivcCylsHigh>
+
+The high-order 4 bytes of the total number of cylinders.
+
+=item C<$uMediaType>
+
+A code for the type of media. See the C<":MEDIA_TYPE"> export class.
+
+=item C<$uTracksPerCyl>
+
+The number of tracks in each cylinder.
+
+=item C<$uSectsPerTrack>
+
+The number of sectors in each track.
+
+=item C<$uBytesPerSect>
+
+The number of bytes in each sector.
+
+=back
+
+=item C<IOCTL_DISK_GET_PARTITION_INFO>
+
+Request information about the size and geometry of the partition.
+C<$pInBuf> should be C<[]>. C<$opOutBuf> will be set to a
+C<PARTITION_INFORMATION> data structure which can be decode via:
+
+ ( $uStartLow, $ivStartHigh, $ucHiddenSects, $uPartitionSeqNumber,
+ $uPartitionType, $bActive, $bRecognized, $bToRewrite )=
+ unpack( "L l L L C c c c", $opOutBuf );
+
+=over
+
+=item C<$uStartLow> and C<$ivStartHigh>
+
+The low-order and high-order [respectively] 4 bytes of the starting
+offset of the partition, measured in bytes.
+
+=item C<$ucHiddenSects>
+
+The number of "hidden" sectors for this partition. Actually this is
+the number of sectors found prior to this partiton, that is, the
+starting offset [as found in C<$uStartLow> and C<$ivStartHigh>]
+divided by the number of bytes per sector.
+
+=item C<$uPartitionSeqNumber>
+
+The sequence number of this partition. Partitions are numbered
+starting as C<1> [with "partition 0" meaning the entire disk].
+Sometimes this field may be C<0> and you'll have to infer the
+partition sequence number from how many partitions preceed it on
+the disk.
+
+=item C<$uPartitionType>
+
+The type of partition. See the C<":PARTITION_"> export class for a
+list of known types. See also C<IsRecognizedPartition> and
+C<IsContainerPartition>.
+
+=item C<$bActive>
+
+C<1> for the active [boot] partition, C<0> otherwise.
+
+=item C<$bRecognized>
+
+Whether this type of partition is support under Win32.
+
+=item C<$bToRewrite>
+
+Whether to update this partition information. This field is not used
+by C<IOCTL_DISK_GET_PARTITION_INFO>. For
+C<IOCTL_DISK_SET_DRIVE_LAYOUT>, you must set this field to a true
+value for any partitions you wish to have changed, added, or deleted.
+
+=back
+
+=item C<IOCTL_DISK_SET_PARTITION_INFO>
+
+Change the type of the partition. C<$opOutBuf> should be C<[]>.
+C<$pInBuf> should be a C<SET_PARTITION_INFORMATION> data structure
+which is just a single byte containing the new parition type [see
+the C<":PARTITION_"> export class for a list of known types]:
+
+ $pInBuf= pack( "C", $uPartitionType );
+
+=item C<IOCTL_DISK_GET_DRIVE_LAYOUT>
+
+Request information about the disk layout. C<$pInBuf> should be C<[]>.
+C<$opOutBuf> will be set to contain C<DRIVE_LAYOUT_INFORMATION>
+structure including several C<PARTITION_INFORMATION> structures:
+
+ my( $cPartitions, $uDiskSignature )= unpack( "L L", $opOutBuf );
+ my @fields= unpack( "x8" . ( "L l L L C c c c" x $cPartitions ),
+ $opOutBuf );
+ my( @uStartLow, @ivStartHigh, @ucHiddenSects,
+ @uPartitionSeqNumber, @uPartitionType, @bActive,
+ @bRecognized, @bToRewrite )= ();
+ for( 1..$cPartition ) {
+ push( @uStartLow, unshift @fields );
+ push( @ivStartHigh, unshift @fields );
+ push( @ucHiddenSects, unshift @fields );
+ push( @uPartitionSeqNumber, unshift @fields );
+ push( @uPartitionType, unshift @fields );
+ push( @bActive, unshift @fields );
+ push( @bRecognized, unshift @fields );
+ push( @bToRewrite, unshift @fields );
+ }
+
+=over
+
+=item C<$cPartitions>
+
+If the number of partitions on the disk.
+
+=item C<$uDiskSignature>
+
+Is the disk signature, a unique number assigned by Disk Administrator
+[F<WinDisk.exe>] and used to identify the disk. This allows drive
+letters for partitions on that disk to remain constant even if the
+SCSI Target ID of the disk gets changed.
+
+=back
+
+See C<IOCTL_DISK_GET_PARTITION_INFORMATION> for information on the
+remaining these fields.
+
+=item C<IOCTL_DISK_GET_MEDIA_TYPES>
+
+Is supposed to be superseded by C<IOCTL_STORAGE_GET_MEDIA_TYPES> but
+is still useful for determining the types of floppy diskette formats
+that can be produced by a given floppy drive. See
+F<ex/FormatFloppy.plx> for an example.
+
+=item C<IOCTL_DISK_SET_DRIVE_LAYOUT>
+
+Change the partition layout of the disk. C<$pOutBuf> should be C<[]>.
+C<$pInBuf> should be a C<DISK_LAYOUT_INFORMATION> data structure
+including several C<PARTITION_INFORMATION> data structures.
+
+ # Already set: $cPartitions, $uDiskSignature, @uStartLow, @ivStartHigh,
+ # @ucHiddenSects, @uPartitionSeqNumber, @uPartitionType, @bActive,
+ # @bRecognized, and @bToRewrite.
+ my( @fields, $prtn )= ();
+ for $prtn ( 1..$cPartition ) {
+ push( @fields, $uStartLow[$prtn-1], $ivStartHigh[$prtn-1],
+ $ucHiddenSects[$prtn-1], $uPartitionSeqNumber[$prtn-1],
+ $uPartitionType[$prtn-1], $bActive[$prtn-1],
+ $bRecognized[$prtn-1], $bToRewrite[$prtn-1] );
+ }
+ $pInBuf= pack( "L L" . ( "L l L L C c c c" x $cPartitions ),
+ $cPartitions, $uDiskSignature, @fields );
+
+To delete a partition, zero out all fields except for C<$bToRewrite>
+which should be set to C<1>. To add a partition, increment
+C<$cPartitions> and add the information for the new partition
+into the arrays, making sure that you insert C<1> into @bToRewrite.
+
+See C<IOCTL_DISK_GET_DRIVE_LAYOUT> and
+C<IOCTL_DISK_GET_PARITITON_INFORMATION> for descriptions of the
+fields.
+
+=item C<IOCTL_DISK_VERIFY>
+
+Performs a logical format of [part of] the disk. C<$opOutBuf> should
+be C<[]>. C<$pInBuf> should contain a C<VERIFY_INFORMATION> data
+structure:
+
+ $pInBuf= pack( "L l L",
+ $uStartOffsetLow, $ivStartOffsetHigh, $uLength );
+
+=over
+
+=item C<$uStartOffsetLow> and C<$ivStartOffsetHigh>
+
+The low-order and high-order [respectively] 4 bytes of the offset [in
+bytes] where the formatting should begin.
+
+=item C<$uLength>
+
+The length [in bytes] of the section to be formatted.
+
+=back
+
+=item C<IOCTL_DISK_FORMAT_TRACKS>
+
+Format a range of tracks on the disk. C<$opOutBuf> should be C<[]>.
+C<$pInBuf> should contain a C<FORMAT_PARAMETERS> data structure:
+
+ $pInBuf= pack( "L L L L L", $uMediaType,
+ $uStartCyl, $uEndCyl, $uStartHead, $uEndHead );
+
+C<$uMediaType> if the type of media to be formatted. Mostly used to
+specify the density to use when formatting a floppy diskette. See the
+C<":MEDIA_TYPE"> export class for more information.
+
+The remaining fields specify the starting and ending cylinder and
+head of the range of tracks to be formatted.
+
+=item C<IOCTL_DISK_REASSIGN_BLOCKS>
+
+Reassign a list of disk blocks to the disk's spare-block pool.
+C<$opOutBuf> should be C<[]>. C<$pInBuf> should be a
+C<REASSIGN_BLOCKS> data structure:
+
+ $pInBuf= pack( "S S L*", 0, $cBlocks, @uBlockNumbers );
+
+=item C<IOCTL_DISK_PERFORMANCE>
+
+Request information about disk performance. C<$pInBuf> should be C<[]>.
+C<$opOutBuf> will be set to contain a C<DISK_PERFORMANCE> data structure:
+
+ my( $ucBytesReadLow, $ivcBytesReadHigh,
+ $ucBytesWrittenLow, $ivcBytesWrittenHigh,
+ $uReadTimeLow, $ivReadTimeHigh,
+ $uWriteTimeLow, $ivWriteTimeHigh,
+ $ucReads, $ucWrites, $uQueueDepth )=
+ unpack( "L l L l L l L l L L L", $opOutBuf );
+
+=item C<IOCTL_DISK_IS_WRITABLE>
+
+No documentation on this IOCTL operation was found.
+
+=item C<IOCTL_DISK_LOGGING>
+
+Control disk logging. Little documentation for this IOCTL operation
+was found. It makes use of a C<DISK_LOGGING> data structure:
+
+=over
+
+=item DISK_LOGGING_START
+
+Start logging each disk request in a buffer internal to the disk device
+driver of size C<$uLogBufferSize>:
+
+ $pInBuf= pack( "C L L", 0, 0, $uLogBufferSize );
+
+=item DISK_LOGGING_STOP
+
+Stop loggin each disk request:
+
+ $pInBuf= pack( "C L L", 1, 0, 0 );
+
+=item DISK_LOGGING_DUMP
+
+Copy the interal log into the supplied buffer:
+
+ $pLogBuffer= ' ' x $uLogBufferSize
+ $pInBuf= pack( "C P L", 2, $pLogBuffer, $uLogBufferSize );
+
+ ( $uByteOffsetLow[$i], $ivByteOffsetHigh[$i],
+ $uStartTimeLow[$i], $ivStartTimeHigh[$i],
+ $uEndTimeLog[$i], $ivEndTimeHigh[$i],
+ $hVirtualAddress[$i], $ucBytes[$i],
+ $uDeviceNumber[$i], $bWasReading[$i] )=
+ unpack( "x".(8+8+8+4+4+1+1+2)." L l L l L l L L C c x2", $pLogBuffer );
+
+=item DISK_LOGGING_BINNING
+
+Keep statics grouped into bins based on request sizes.
+
+ $pInBuf= pack( "C P L", 3, $pUnknown, $uUnknownSize );
+
+=back
+
+=item C<IOCTL_DISK_FORMAT_TRACKS_EX>
+
+No documentation on this IOCTL is included.
+
+=item C<IOCTL_DISK_HISTOGRAM_STRUCTURE>
+
+No documentation on this IOCTL is included.
+
+=item C<IOCTL_DISK_HISTOGRAM_DATA>
+
+No documentation on this IOCTL is included.
+
+=item C<IOCTL_DISK_HISTOGRAM_RESET>
+
+No documentation on this IOCTL is included.
+
+=item C<IOCTL_DISK_REQUEST_STRUCTURE>
+
+No documentation on this IOCTL operation was found.
+
+=item C<IOCTL_DISK_REQUEST_DATA>
+
+No documentation on this IOCTL operation was found.
+
+=back
+
+=item C<":FSCTL_">
+
+File system control operations. Used in the C<$uIoControlCode>
+argument to C<DeviceIoControl>.
+
+Includes C<FSCTL_SET_REPARSE_POINT>, C<FSCTL_GET_REPARSE_POINT>,
+C<FSCTL_DELETE_REPARSE_POINT>.
+
+=over
+
+=item C<FSCTL_SET_REPARSE_POINT>
+
+Sets reparse point data to be associated with $hDevice.
+
+=item C<FSCTL_GET_REPARSE_POINT>
+
+Retrieves the reparse point data associated with $hDevice.
+
+=item C<FSCTL_DELETE_REPARSE_POINT>
+
+Deletes the reparse point data associated with $hDevice.
+
+=back
+
+=item C<":GENERIC_">
+
+Constants specifying generic access permissions that are not specific
+to one type of object.
+
+ GENERIC_ALL GENERIC_EXECUTE
+ GENERIC_READ GENERIC_WRITE
+
+=item C<":MEDIA_TYPE">
+
+Different classes of media that a device can support. Used in the
+C<$uMediaType> field of a C<DISK_GEOMETRY> structure.
+
+=over
+
+=item C<Unknown>
+
+Format is unknown.
+
+=item C<F5_1Pt2_512>
+
+5.25" floppy, 1.2MB [really 1,200KB] total space, 512 bytes/sector.
+
+=item C<F3_1Pt44_512>
+
+3.5" floppy, 1.44MB [really 1,440KB] total space, 512 bytes/sector.
+
+=item C<F3_2Pt88_512>
+
+3.5" floppy, 2.88MB [really 2,880KB] total space, 512 bytes/sector.
+
+=item C<F3_20Pt8_512>
+
+3.5" floppy, 20.8MB total space, 512 bytes/sector.
+
+=item C<F3_720_512>
+
+3.5" floppy, 720KB total space, 512 bytes/sector.
+
+=item C<F5_360_512>
+
+5.25" floppy, 360KB total space, 512 bytes/sector.
+
+=item C<F5_320_512>
+
+5.25" floppy, 320KB total space, 512 bytes/sector.
+
+=item C<F5_320_1024>
+
+5.25" floppy, 320KB total space, 1024 bytes/sector.
+
+=item C<F5_180_512>
+
+5.25" floppy, 180KB total space, 512 bytes/sector.
+
+=item C<F5_160_512>
+
+5.25" floppy, 160KB total space, 512 bytes/sector.
+
+=item C<RemovableMedia>
+
+Some type of removable media other than a floppy diskette.
+
+=item C<FixedMedia>
+
+A fixed hard disk.
+
+=item C<F3_120M_512>
+
+3.5" floppy, 120MB total space.
+
+=back
+
+=item C<":MOVEFILE_">
+
+Constants for use in C<$uFlags> arguments to C<MoveFileEx>.
+
+ MOVEFILE_COPY_ALLOWED MOVEFILE_DELAY_UNTIL_REBOOT
+ MOVEFILE_REPLACE_EXISTING MOVEFILE_WRITE_THROUGH
+
+=item C<":SECURITY_">
+
+Security quality of service values that can be used in the C<$uFlags>
+argument to C<CreateFile> if opening the client side of a named pipe.
+
+ SECURITY_ANONYMOUS SECURITY_CONTEXT_TRACKING
+ SECURITY_DELEGATION SECURITY_EFFECTIVE_ONLY
+ SECURITY_IDENTIFICATION SECURITY_IMPERSONATION
+ SECURITY_SQOS_PRESENT
+
+=item C<":SEM_">
+
+Constants to be used with C<SetErrorMode>.
+
+ SEM_FAILCRITICALERRORS SEM_NOGPFAULTERRORBOX
+ SEM_NOALIGNMENTFAULTEXCEPT SEM_NOOPENFILEERRORBOX
+
+=item C<":PARTITION_">
+
+Constants describing partition types.
+
+ PARTITION_ENTRY_UNUSED PARTITION_FAT_12
+ PARTITION_XENIX_1 PARTITION_XENIX_2
+ PARTITION_FAT_16 PARTITION_EXTENDED
+ PARTITION_HUGE PARTITION_IFS
+ PARTITION_FAT32 PARTITION_FAT32_XINT13
+ PARTITION_XINT13 PARTITION_XINT13_EXTENDED
+ PARTITION_PREP PARTITION_UNIX
+ VALID_NTFT PARTITION_NTFT
+
+=item C<":ALL">
+
+All of the above.
+
+=back
+
+=head1 BUGS
+
+None known at this time.
+
+=head1 AUTHOR
+
+Tye McQueen, tye@metronet.com, http://www.metronet.com/~tye/.
+
+=head1 SEE ALSO
+
+The pyramids.
+
+=cut
diff --git a/Master/tlpkg/tlperl/lib/Win32API/File/cFile.pc b/Master/tlpkg/tlperl/lib/Win32API/File/cFile.pc
new file mode 100644
index 00000000000..da00f413aa2
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Win32API/File/cFile.pc
@@ -0,0 +1,165 @@
+# Generated by cFile_pc.cxx.
+# Package Win32API::File with options:
+# CPLUSPLUS => q[1]
+# IFDEF => q[!/[a-z\d]/]
+# IMPORT_LIST => [q[/._/], q[!/[a-z]/], q[:MEDIA_TYPE]]
+# WRITE_PERL => q[1]
+# Perl files eval'd:
+# File.pm => last if /^\s*(bootstrap|XSLoader::load)\b/
+# C files included:
+# File.xs => last if m#/[/*]\s*CONSTS_DEFINED\b|^\s*MODULE\b#
+sub CREATE_ALWAYS () { 2 }
+sub CREATE_NEW () { 1 }
+sub DDD_EXACT_MATCH_ON_REMOVE () { 4 }
+sub DDD_RAW_TARGET_PATH () { 1 }
+sub DDD_REMOVE_DEFINITION () { 2 }
+sub DRIVE_CDROM () { 5 }
+sub DRIVE_FIXED () { 3 }
+sub DRIVE_NO_ROOT_DIR () { 1 }
+sub DRIVE_RAMDISK () { 6 }
+sub DRIVE_REMOTE () { 4 }
+sub DRIVE_REMOVABLE () { 2 }
+sub DRIVE_UNKNOWN () { 0 }
+sub F3_120M_512 () { 13 }
+sub F3_1Pt44_512 () { 2 }
+sub F3_20Pt8_512 () { 4 }
+sub F3_2Pt88_512 () { 3 }
+sub F3_720_512 () { 5 }
+sub F5_160_512 () { 10 }
+sub F5_180_512 () { 9 }
+sub F5_1Pt2_512 () { 1 }
+sub F5_320_1024 () { 8 }
+sub F5_320_512 () { 7 }
+sub F5_360_512 () { 6 }
+sub FILE_ADD_FILE () { 2 }
+sub FILE_ADD_SUBDIRECTORY () { 4 }
+sub FILE_ALL_ACCESS () { 2032127 }
+sub FILE_APPEND_DATA () { 4 }
+sub FILE_ATTRIBUTE_ARCHIVE () { 32 }
+sub FILE_ATTRIBUTE_COMPRESSED () { 2048 }
+sub FILE_ATTRIBUTE_DEVICE () { 0x00000040 }
+sub FILE_ATTRIBUTE_DIRECTORY () { 0x00000010 }
+sub FILE_ATTRIBUTE_ENCRYPTED () { 0x00004000 }
+sub FILE_ATTRIBUTE_HIDDEN () { 2 }
+sub FILE_ATTRIBUTE_NORMAL () { 128 }
+sub FILE_ATTRIBUTE_NOT_CONTENT_INDEXED () { 0x00002000 }
+sub FILE_ATTRIBUTE_OFFLINE () { 4096 }
+sub FILE_ATTRIBUTE_READONLY () { 1 }
+sub FILE_ATTRIBUTE_REPARSE_POINT () { 0x00000400 }
+sub FILE_ATTRIBUTE_SPARSE_FILE () { 0x00000200 }
+sub FILE_ATTRIBUTE_SYSTEM () { 4 }
+sub FILE_ATTRIBUTE_TEMPORARY () { 256 }
+sub FILE_BEGIN () { 0 }
+sub FILE_CREATE_PIPE_INSTANCE () { 4 }
+sub FILE_CURRENT () { 1 }
+sub FILE_DELETE_CHILD () { 64 }
+sub FILE_END () { 2 }
+sub FILE_EXECUTE () { 32 }
+sub FILE_FLAG_BACKUP_SEMANTICS () { 33554432 }
+sub FILE_FLAG_DELETE_ON_CLOSE () { 67108864 }
+sub FILE_FLAG_NO_BUFFERING () { 536870912 }
+sub FILE_FLAG_OPEN_REPARSE_POINT () { 0x200000 }
+sub FILE_FLAG_OVERLAPPED () { 1073741824 }
+sub FILE_FLAG_POSIX_SEMANTICS () { 16777216 }
+sub FILE_FLAG_RANDOM_ACCESS () { 268435456 }
+sub FILE_FLAG_SEQUENTIAL_SCAN () { 134217728 }
+sub FILE_FLAG_WRITE_THROUGH () { 0x80000000 }
+sub FILE_GENERIC_EXECUTE () { 1179808 }
+sub FILE_GENERIC_READ () { 1179785 }
+sub FILE_GENERIC_WRITE () { 1179926 }
+sub FILE_LIST_DIRECTORY () { 1 }
+sub FILE_READ_ATTRIBUTES () { 128 }
+sub FILE_READ_DATA () { 1 }
+sub FILE_READ_EA () { 8 }
+sub FILE_SHARE_DELETE () { 4 }
+sub FILE_SHARE_READ () { 1 }
+sub FILE_SHARE_WRITE () { 2 }
+sub FILE_TRAVERSE () { 32 }
+sub FILE_TYPE_CHAR () { 2 }
+sub FILE_TYPE_DISK () { 1 }
+sub FILE_TYPE_PIPE () { 3 }
+sub FILE_TYPE_UNKNOWN () { 0 }
+sub FILE_WRITE_ATTRIBUTES () { 256 }
+sub FILE_WRITE_DATA () { 2 }
+sub FILE_WRITE_EA () { 16 }
+sub FS_CASE_IS_PRESERVED () { 2 }
+sub FS_CASE_SENSITIVE () { 1 }
+sub FS_FILE_COMPRESSION () { 16 }
+sub FS_PERSISTENT_ACLS () { 8 }
+sub FS_UNICODE_STORED_ON_DISK () { 4 }
+sub FS_VOL_IS_COMPRESSED () { 32768 }
+sub FSCTL_SET_REPARSE_POINT () { (9 << 16 | 0 << 14 | 41 << 2 | 0) }
+sub FSCTL_GET_REPARSE_POINT () { (9 << 16 | 0 << 14 | 42 << 2 | 0) }
+sub FSCTL_DELETE_REPARSE_POINT () { (9 << 16 | 0 << 14 | 43 << 2 | 0) }
+sub FixedMedia () { 12 }
+sub GENERIC_ALL () { 268435456 }
+sub GENERIC_EXECUTE () { 536870912 }
+sub GENERIC_READ () { 0x80000000 }
+sub GENERIC_WRITE () { 1073741824 }
+sub HANDLE_FLAG_INHERIT () { 1 }
+sub HANDLE_FLAG_PROTECT_FROM_CLOSE () { 2 }
+sub INVALID_FILE_ATTRIBUTES () { 0xFFFFFFFF }
+sub INVALID_HANDLE_VALUE () { 0xffffffff }
+sub IOCTL_DISK_FORMAT_TRACKS () { 507928 }
+sub IOCTL_DISK_FORMAT_TRACKS_EX () { 507948 }
+sub IOCTL_DISK_GET_DRIVE_GEOMETRY () { 458752 }
+sub IOCTL_DISK_GET_DRIVE_LAYOUT () { 475148 }
+sub IOCTL_DISK_GET_MEDIA_TYPES () { 461824 }
+sub IOCTL_DISK_GET_PARTITION_INFO () { 475140 }
+sub IOCTL_DISK_HISTOGRAM_DATA () { 458804 }
+sub IOCTL_DISK_HISTOGRAM_RESET () { 458808 }
+sub IOCTL_DISK_HISTOGRAM_STRUCTURE () { 458800 }
+sub IOCTL_DISK_IS_WRITABLE () { 458788 }
+sub IOCTL_DISK_LOGGING () { 458792 }
+sub IOCTL_DISK_PERFORMANCE () { 458784 }
+sub IOCTL_DISK_REASSIGN_BLOCKS () { 507932 }
+sub IOCTL_DISK_REQUEST_DATA () { 458816 }
+sub IOCTL_DISK_REQUEST_STRUCTURE () { 458812 }
+sub IOCTL_DISK_SET_DRIVE_LAYOUT () { 507920 }
+sub IOCTL_DISK_SET_PARTITION_INFO () { 507912 }
+sub IOCTL_DISK_VERIFY () { 458772 }
+sub IOCTL_STORAGE_CHECK_VERIFY () { 2967552 }
+sub IOCTL_STORAGE_EJECT_MEDIA () { 2967560 }
+sub IOCTL_STORAGE_FIND_NEW_DEVICES () { 2967576 }
+sub IOCTL_STORAGE_GET_MEDIA_TYPES () { 2952192 }
+sub IOCTL_STORAGE_LOAD_MEDIA () { 2967564 }
+sub IOCTL_STORAGE_MEDIA_REMOVAL () { 2967556 }
+sub IOCTL_STORAGE_RELEASE () { 2967572 }
+sub IOCTL_STORAGE_RESERVE () { 2967568 }
+sub MOVEFILE_COPY_ALLOWED () { 2 }
+sub MOVEFILE_DELAY_UNTIL_REBOOT () { 4 }
+sub MOVEFILE_REPLACE_EXISTING () { 1 }
+sub MOVEFILE_WRITE_THROUGH () { 8 }
+sub OPEN_ALWAYS () { 4 }
+sub OPEN_EXISTING () { 3 }
+sub PARTITION_ENTRY_UNUSED () { 0 }
+sub PARTITION_EXTENDED () { 5 }
+sub PARTITION_FAT32 () { 11 }
+sub PARTITION_FAT32_XINT13 () { 12 }
+sub PARTITION_FAT_12 () { 1 }
+sub PARTITION_FAT_16 () { 4 }
+sub PARTITION_HUGE () { 6 }
+sub PARTITION_IFS () { 7 }
+sub PARTITION_NTFT () { 128 }
+sub PARTITION_PREP () { 65 }
+sub PARTITION_UNIX () { 99 }
+sub PARTITION_XENIX_1 () { 2 }
+sub PARTITION_XENIX_2 () { 3 }
+sub PARTITION_XINT13 () { 14 }
+sub PARTITION_XINT13_EXTENDED () { 15 }
+sub RemovableMedia () { 11 }
+sub SECURITY_ANONYMOUS () { 0 }
+sub SECURITY_CONTEXT_TRACKING () { 262144 }
+sub SECURITY_DELEGATION () { 196608 }
+sub SECURITY_EFFECTIVE_ONLY () { 524288 }
+sub SECURITY_IDENTIFICATION () { 65536 }
+sub SECURITY_IMPERSONATION () { 131072 }
+sub SECURITY_SQOS_PRESENT () { 1048576 }
+sub SEM_FAILCRITICALERRORS () { 1 }
+sub SEM_NOALIGNMENTFAULTEXCEPT () { 4 }
+sub SEM_NOGPFAULTERRORBOX () { 2 }
+sub SEM_NOOPENFILEERRORBOX () { 32768 }
+sub TRUNCATE_EXISTING () { 5 }
+sub Unknown () { 0 }
+sub VALID_NTFT () { 192 }
+1;
diff --git a/Master/tlpkg/tlperl/lib/Win32API/Registry.pm b/Master/tlpkg/tlperl/lib/Win32API/Registry.pm
new file mode 100644
index 00000000000..2a1657c3b5b
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Win32API/Registry.pm
@@ -0,0 +1,1775 @@
+# Registry.pm -- Low-level access to functions/constants from WINREG.h
+
+package Win32API::Registry;
+
+use strict;
+use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS); #@EXPORT_FAIL);
+$VERSION= '0.32';
+
+require Exporter;
+require DynaLoader;
+@ISA= qw(Exporter DynaLoader);
+
+@EXPORT= qw();
+%EXPORT_TAGS= (
+ Func => [qw( regConstant regLastError
+ AllowPriv AbortSystemShutdown InitiateSystemShutdown
+ RegCloseKey RegConnectRegistry RegCreateKey
+ RegCreateKeyEx RegDeleteKey RegDeleteValue
+ RegEnumKey RegEnumKeyEx RegEnumValue
+ RegFlushKey RegGetKeySecurity RegLoadKey
+ RegNotifyChangeKeyValue RegOpenKey RegOpenKeyEx
+ RegQueryInfoKey RegQueryMultipleValues RegQueryValue
+ RegQueryValueEx RegReplaceKey RegRestoreKey
+ RegSaveKey RegSetKeySecurity RegSetValue
+ RegSetValueEx RegUnLoadKey )],
+ FuncA => [qw(
+ AbortSystemShutdownA InitiateSystemShutdownA
+ RegConnectRegistryA RegCreateKeyA RegCreateKeyExA
+ RegDeleteKeyA RegDeleteValueA RegEnumKeyA
+ RegEnumKeyExA RegEnumValueA RegLoadKeyA
+ RegOpenKeyA RegOpenKeyExA RegQueryInfoKeyA
+ RegQueryMultipleValuesA RegQueryValueA RegQueryValueExA
+ RegReplaceKeyA RegRestoreKeyA RegSaveKeyA
+ RegSetValueA RegSetValueExA RegUnLoadKeyA )],
+ FuncW => [qw(
+ AbortSystemShutdownW InitiateSystemShutdownW
+ RegConnectRegistryW RegCreateKeyW RegCreateKeyExW
+ RegDeleteKeyW RegDeleteValueW RegEnumKeyW
+ RegEnumKeyExW RegEnumValueW RegLoadKeyW
+ RegOpenKeyW RegOpenKeyExW RegQueryInfoKeyW
+ RegQueryMultipleValuesW RegQueryValueW RegQueryValueExW
+ RegReplaceKeyW RegRestoreKeyW RegSaveKeyW
+ RegSetValueW RegSetValueExW RegUnLoadKeyW )],
+ HKEY_ => [qw(
+ HKEY_CLASSES_ROOT HKEY_CURRENT_CONFIG HKEY_CURRENT_USER
+ HKEY_DYN_DATA HKEY_LOCAL_MACHINE HKEY_PERFORMANCE_DATA
+ HKEY_USERS )],
+ KEY_ => [qw(
+ KEY_QUERY_VALUE KEY_SET_VALUE KEY_CREATE_SUB_KEY
+ KEY_ENUMERATE_SUB_KEYS KEY_NOTIFY KEY_CREATE_LINK
+ KEY_READ KEY_WRITE KEY_EXECUTE
+ KEY_ALL_ACCESS),
+ 'KEY_DELETE', # DELETE (0x00010000L)
+ 'KEY_READ_CONTROL', # READ_CONTROL (0x00020000L)
+ 'KEY_WRITE_DAC', # WRITE_DAC (0x00040000L)
+ 'KEY_WRITE_OWNER', # WRITE_OWNER (0x00080000L)
+ 'KEY_SYNCHRONIZE', # SYNCHRONIZE (0x00100000L) (not used)
+ ],
+ REG_ => [qw(
+ REG_OPTION_RESERVED REG_OPTION_NON_VOLATILE REG_OPTION_VOLATILE
+ REG_OPTION_CREATE_LINK REG_OPTION_BACKUP_RESTORE
+ REG_OPTION_OPEN_LINK REG_LEGAL_OPTION REG_CREATED_NEW_KEY
+ REG_OPENED_EXISTING_KEY REG_WHOLE_HIVE_VOLATILE REG_REFRESH_HIVE
+ REG_NO_LAZY_FLUSH REG_NOTIFY_CHANGE_ATTRIBUTES
+ REG_NOTIFY_CHANGE_NAME REG_NOTIFY_CHANGE_LAST_SET
+ REG_NOTIFY_CHANGE_SECURITY REG_LEGAL_CHANGE_FILTER
+ REG_NONE REG_SZ REG_EXPAND_SZ
+ REG_BINARY REG_DWORD REG_DWORD_LITTLE_ENDIAN
+ REG_DWORD_BIG_ENDIAN REG_LINK REG_MULTI_SZ
+ REG_RESOURCE_LIST REG_FULL_RESOURCE_DESCRIPTOR
+ REG_RESOURCE_REQUIREMENTS_LIST )],
+ SE_ => [qw(
+ SE_ASSIGNPRIMARYTOKEN_NAME SE_AUDIT_NAME
+ SE_BACKUP_NAME SE_CHANGE_NOTIFY_NAME
+ SE_CREATE_PAGEFILE_NAME SE_CREATE_PERMANENT_NAME
+ SE_CREATE_TOKEN_NAME SE_DEBUG_NAME
+ SE_INCREASE_QUOTA_NAME SE_INC_BASE_PRIORITY_NAME
+ SE_LOAD_DRIVER_NAME SE_LOCK_MEMORY_NAME
+ SE_MACHINE_ACCOUNT_NAME SE_PROF_SINGLE_PROCESS_NAME
+ SE_REMOTE_SHUTDOWN_NAME SE_RESTORE_NAME
+ SE_SECURITY_NAME SE_SHUTDOWN_NAME
+ SE_SYSTEMTIME_NAME SE_SYSTEM_ENVIRONMENT_NAME
+ SE_SYSTEM_PROFILE_NAME SE_TAKE_OWNERSHIP_NAME
+ SE_TCB_NAME SE_UNSOLICITED_INPUT_NAME )],
+);
+@EXPORT_OK= ();
+{ my $ref;
+ foreach $ref ( values(%EXPORT_TAGS) ) {
+ push( @EXPORT_OK, @$ref ) unless $ref->[0] =~ /^SE_/;
+ }
+}
+$EXPORT_TAGS{ALL}= [ @EXPORT_OK ]; # \@EXPORT_OK once SE_* settles down.
+# push( @EXPORT_OK, "JHEREG_TACOSALAD" ); # Used to test Mkconst2perl
+push( @EXPORT_OK, @{$EXPORT_TAGS{SE_}} );
+
+bootstrap Win32API::Registry $VERSION;
+
+# Preloaded methods go here.
+
+# To convert C constants to Perl code in cRegistry.pc
+# [instead of C or C++ code in cRegistry.h]:
+# * Modify F<Makefile.PL> to add WriteMakeFile() =>
+# CONST2PERL/postamble => [[ "Win32API::Registry" => ]] WRITE_PERL => 1.
+# * Either comment out C<#include "cRegistry.h"> from F<Registry.xs>
+# or make F<cRegistry.h> an empty file.
+# * Make sure the following C<if> block is not commented out.
+# * "nmake clean", "perl Makefile.PL", "nmake"
+
+if( ! defined &REG_NONE ) {
+ require "Win32API/Registry/cRegistry.pc";
+}
+
+# This would be convenient but inconsistant and hard to explain:
+#push( @{$EXPORT_TAGS{ALL}}, @{$EXPORT_TAGS{SE_}} )
+# if defined &SE_TCB_NAME;
+
+sub regConstant
+{
+ my( $name )= @_;
+ if( 1 != @_ || ! $name || $name =~ /\W/ ) {
+ require Carp;
+ Carp::croak( 'Usage: ',__PACKAGE__,'::regConstant("CONST_NAME")' );
+ }
+ my $proto= prototype $name;
+ if( defined \&$name
+ && defined $proto
+ && "" eq $proto ) {
+ no strict 'refs';
+ return &$name;
+ }
+ return undef;
+}
+
+# We provide this for backwards compatibility:
+sub constant
+{
+ my( $name )= @_;
+ my $value= regConstant( $name );
+ if( defined $value ) {
+ $!= 0;
+ return $value;
+ }
+ $!= 11; # EINVAL
+ return 0;
+}
+
+BEGIN {
+ my $code= 'return _regLastError(@_)';
+ local( $!, $^E )= ( 1, 1 );
+ if( $! ne $^E ) {
+ $code= '
+ local( $^E )= _regLastError(@_);
+ my $ret= $^E;
+ return $ret;
+ ';
+ }
+ eval "sub regLastError { $code }";
+ die "$@" if $@;
+}
+
+# Since we ISA DynaLoader which ISA AutoLoader, we ISA AutoLoader so we
+# need this next chunk to prevent Win32API::Registry->nonesuch() from
+# looking for "nonesuch.al" and producing confusing error messages:
+use vars qw($AUTOLOAD);
+sub AUTOLOAD {
+ require Carp;
+ Carp::croak(
+ "Can't locate method $AUTOLOAD via package Win32API::Registry" );
+}
+
+# Replace "&rout;" with "goto &rout;" when that is supported on Win32.
+
+# Let user omit all buffer sizes:
+sub RegEnumKeyExA {
+ if( 6 == @_ ) { splice(@_,4,0,[]); splice(@_,2,0,[]); }
+ &_RegEnumKeyExA;
+}
+sub RegEnumKeyExW {
+ if( 6 == @_ ) { splice(@_,4,0,[]); splice(@_,2,0,[]); }
+ &_RegEnumKeyExW;
+}
+sub RegEnumValueA {
+ if( 6 == @_ ) { splice(@_,2,0,[]); push(@_,[]); }
+ &_RegEnumValueA;
+}
+sub RegEnumValueW {
+ if( 6 == @_ ) { splice(@_,2,0,[]); push(@_,[]); }
+ &_RegEnumValueW;
+}
+sub RegQueryInfoKeyA {
+ if( 11 == @_ ) { splice(@_,2,0,[]); }
+ &_RegQueryInfoKeyA;
+}
+sub RegQueryInfoKeyW {
+ if( 11 == @_ ) { splice(@_,2,0,[]); }
+ &_RegQueryInfoKeyW;
+}
+
+sub RegEnumKeyA {
+ push(@_,[]) if 3 == @_;
+ &_RegEnumKeyA;
+}
+sub RegEnumKeyW {
+ push(@_,[]) if 3 == @_;
+ &_RegEnumKeyW;
+}
+sub RegGetKeySecurity {
+ push(@_,[]) if 3 == @_;
+ &_RegGetKeySecurity;
+}
+sub RegQueryMultipleValuesA {
+ push(@_,[]) if 4 == @_;
+ &_RegQueryMultipleValuesA;
+}
+sub RegQueryMultipleValuesW {
+ push(@_,[]) if 4 == @_;
+ &_RegQueryMultipleValuesW;
+}
+sub RegQueryValueA {
+ push(@_,[]) if 3 == @_;
+ &_RegQueryValueA;
+}
+sub RegQueryValueW {
+ push(@_,[]) if 3 == @_;
+ &_RegQueryValueW;
+}
+sub RegQueryValueExA {
+ push(@_,[]) if 5 == @_;
+ &_RegQueryValueExA;
+}
+sub RegQueryValueExW {
+ push(@_,[]) if 5 == @_;
+ &_RegQueryValueExW;
+}
+sub RegSetValueA {
+ push(@_,0) if 4 == @_;
+ &_RegSetValueA;
+}
+sub RegSetValueW {
+ push(@_,0) if 4 == @_;
+ &_RegSetValueW;
+}
+sub RegSetValueExA {
+ push(@_,0) if 5 == @_;
+ &_RegSetValueExA;
+}
+sub RegSetValueExW {
+ push(@_,0) if 5 == @_;
+ &_RegSetValueExW;
+}
+
+# Aliases for non-Unicode functions:
+sub AbortSystemShutdown { &AbortSystemShutdownA; }
+sub InitiateSystemShutdown { &InitiateSystemShutdownA; }
+sub RegConnectRegistry { &RegConnectRegistryA; }
+sub RegCreateKey { &RegCreateKeyA; }
+sub RegCreateKeyEx { &RegCreateKeyExA; }
+sub RegDeleteKey { &RegDeleteKeyA; }
+sub RegDeleteValue { &RegDeleteValueA; }
+sub RegEnumKey { &RegEnumKeyA; }
+sub RegEnumKeyEx { &RegEnumKeyExA; }
+sub RegEnumValue { &RegEnumValueA; }
+sub RegLoadKey { &RegLoadKeyA; }
+sub RegOpenKey { &RegOpenKeyA; }
+sub RegOpenKeyEx { &RegOpenKeyExA; }
+sub RegQueryInfoKey { &RegQueryInfoKeyA; }
+sub RegQueryMultipleValues { &RegQueryMultipleValuesA; }
+sub RegQueryValue { &RegQueryValueA; }
+sub RegQueryValueEx { &RegQueryValueExA; }
+sub RegReplaceKey { &RegReplaceKeyA; }
+sub RegRestoreKey { &RegRestoreKeyA; }
+sub RegSaveKey { &RegSaveKeyA; }
+sub RegSetValue { &RegSetValueA; }
+sub RegSetValueEx { &RegSetValueExA; }
+sub RegUnLoadKey { &RegUnLoadKeyA; }
+
+1;
+__END__
+
+=head1 NAME
+
+Win32API::Registry - Low-level access to Win32 system API calls from WINREG.H
+
+=head1 SYNOPSIS
+
+ use Win32API::Registry 0.21 qw( :ALL );
+
+ RegOpenKeyEx( HKEY_LOCAL_MACHINE, "SYSTEM\\Disk", 0, KEY_READ, $key );
+ or die "Can't open HKEY_LOCAL_MACHINE\\SYSTEM\\Disk: ",
+ regLastError(),"\n";
+ RegQueryValueEx( $key, "Information", [], $type, $data, [] );
+ or die "Can't read HKEY_L*MACHINE\\SYSTEM\\Disk\\Information: ",
+ regLastError(),"\n";
+ [...]
+ RegCloseKey( $key )
+ or die "Can't close HKEY_LOCAL_MACHINE\\SYSTEM\\Disk: ",
+ regLastError(),"\n";
+
+=head1 DESCRIPTION
+
+This provides fairly low-level access to the Win32 System API
+calls dealing with the Registry [mostly from WINREG.H]. This
+is mostly intended to be used by other modules such as
+C<Win32::TieRegistry> [which provides an extremely Perl-friendly
+method for using the Registry].
+
+For a description of the logical structure of the Registry, see
+the documentation for the C<Win32::TieRegistry> module.
+
+To pass in C<NULL> as the pointer to an optional buffer, pass in
+an empty list reference, C<[]>.
+
+Beyond raw access to the API calls and related constants, this module
+handles smart buffer allocation and translation of return codes.
+
+All calls return a true value for success and a false value for
+failure. After any failure, C<$^E> should automatically be set
+to indicate the reason. However, current versions of Perl often
+overwrite C<$^E> too quickly, so you can use C<regLastError()>
+instead, which is only set by Win32API::Registry routines.
+C<regLastError()> is also good if you have a really old version
+of Perl that does not connect C<$^E> to C<GetLastError()> on
+Win32.
+
+Note that C<$!> is not set by these routines except by
+C<Win32API::Registry::constant()> when a constant is not defined.
+
+=head2 Exports
+
+Nothing is exported by default. The following tags can be used to
+have sets of symbols exported.
+
+[Note that much of the following documentation refers to the
+behavior of the underlying API calls which may vary in current
+and future versions of the Win32 API without any changes to this
+module. Therefore you should check the Win32 API documentation
+directly when needed.]
+
+=over
+
+=item :Func
+
+The basic function names:
+
+=over
+
+=item AllowPriv
+
+=item C<AllowPriv( $sPrivName, $bEnable )>
+
+Not a Win32 API call. Enables or disables a specific privilege for
+the current process. Returns a true value if successful and a false
+value [and sets C<$^E>/C<regLastError()>] on failure. This routine
+does not provide a way to tell if a privilege is currently enabled.
+
+C<$sPrivname> is a Win32 privilege name [see L</:SE_>]. For example,
+C<"SeBackupPrivilege"> [a.k.a. C<SE_BACKUP_NAME>] controls whether
+you can use C<RegSaveKey()> and C<"SeRestorePrivilege"> [a.k.a.
+C<SE_RESTORE_NAME>] controls whether you can use C<RegLoadKey()>.
+
+If C<$bEnable> is true, then C<AllowPriv()> tries to enable the
+privilege. Otherwise it tries to disable the privilege.
+
+=item AbortSystemShutdown
+
+=item C<AbortSystemShutdown( $sComputerName )>
+
+Tries to abort a remote shutdown request previously made via
+C<InitiateSystemShutdown()>. Returns a true value if successful
+and a false value [and sets C<$^E>/C<regLastError()>] on failure.
+
+=item InitiateSystemShutdown
+
+=item C<InitiateSystemShutdown( $sComputer, $sMessage, $uTimeoutSecs, $bForce, $bReboot )>
+
+Requests that a [remote] computer be shutdown or rebooted.
+Returns a true value if successful and a false value [and
+sets C<$^E>/C<regLastError()>] on failure.
+
+C<$sComputer> is the name [or address] of the computer to be
+shutdown or rebooted. You can use C<[]> [for C<NULL>] or C<"">
+to indicate the local computer.
+
+C<$sMessage> is the message to be displayed in a pop-up window
+on the desktop of the computer to be shutdown or rebooted until
+the timeout expires or the shutdown is aborted via
+C<AbortSystemShutdown()>. With C<$iTimeoutSecs == 0>, the
+message will never be visible.
+
+C<$iTimeoutSecs> is the number of seconds to wait before starting
+the shutdown.
+
+If C<$bForce> is false, then any applications running on the remote
+computer get a chance to prompt the remote user whether they want
+to save changes. Also, for any applications that do not exit quickly
+enough, the operating system will prompt the user whether they wish
+to wait longer for the application to exit or force it to exit now.
+At any of these prompts the user can press B<CANCEL> to abort the
+shutdown but if no applications have unsaved data, they will likely
+all exit quickly and the shutdown will progress with the remote user
+having no option to cancel the shutdown.
+
+If C<$bForce> is true, all applications are told to exit immediately
+and so will not prompt the user even if there is unsaved data. Any
+applications that take too long to exit will be forcibly killed after
+a short time. The only way to abort the shutdown is to call
+C<AbortSystemShutdown()> before the timeout expires and there is no
+way to abort the shutdown once it has begun.
+
+If C<$bReboot> is true, the computer will automatically reboot once
+the shutdown is complete. If C<$bReboot> is false, then when the
+shutdown is complete the computer will halt at a screen indicating
+that the shutdown is complete and offering a way for the user to
+start to boot the computer.
+
+You must have the C<"SeRemoteShutdownPrivilege"> privilege
+on the remote computer for this call to succeed. If shutting
+down the local computer, then the calling process must have
+the C<"SeShutdownPrivilege"> privilege and have it enabled.
+
+=item RegCloseKey
+
+=item C<RegCloseKey( $hKey )>
+
+Closes the handle to a Registry key returned by C<RegOpenKeyEx()>,
+C<RegConnectRegistry()>, C<RegCreateKeyEx()>, or a few other
+routines. Returns a true value if successful and a false value
+[and sets C<$^E>/C<regLastError()>] on failure.
+
+=item RegConnectRegistry
+
+=item C<RegConnectRegistry( $sComputer, $hRootKey, $ohKey )>
+
+Connects to one of the root Registry keys of a remote computer.
+Returns a true value if successful and a false value [and
+sets C<$^E>/C<regLastError()>] on failure.
+
+C<$sComputer> is the name [or address] of a remote computer
+whose Registry you wish to access.
+
+C<$hKey> must be either C<HKEY_LOCAL_MACHINE> or C<HKEY_USERS>
+and specifies which root Registry key on the remote computer
+you wish to have access to.
+
+C<$phKey> will be set to the handle to be used to access the
+remote Registry key if the call succeeds.
+
+=item regConstant
+
+=item C<$value= regConstant( $sConstantName )>
+
+Fetch the value of a constant. Returns C<undef> if C<$sConstantName>
+is not the name of a constant supported by this module. Never sets
+C<$!> nor C<$^E>.
+
+This function is rarely used since you will usually get the value of a
+constant by having that constant imported into your package by listing
+the constant name in the C<use Win32API::Registry> statement and then
+simply using the constant name in your code [perhaps followed by
+C<()>]. This function is useful for verifying constant names not in
+Perl code, for example, after prompting a user to type in a constant
+name.
+
+=item RegCreateKey
+
+=item C<RegCreateKey( $hKey, $sSubKey, $ohSubKey )>
+
+This routine is meant only for compatibility with Windows version
+3.1. Use C<RegCreateKeyEx()> instead.
+
+=item RegCreateKeyEx
+
+=item C<RegCreateKeyEx( $hKey, $sSubKey, $uZero, $sClass, $uOpts, $uAccess, $pSecAttr, $ohNewKey, $ouDisp )>
+
+Creates a new Registry subkey. Returns a true value if successful and
+a false value [and sets C<$^E>/C<regLastError()>] on failure.
+
+C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
+a previous call].
+
+C<$sSubKey> is the name of the new subkey to be created.
+
+C<$iZero> is reserved for future use and should always be specified
+as C<0>.
+
+C<$sClass> is a string to be used as the class for the new
+subkey. We are not aware of any current use for Registry key
+class information so the empty string, C<"">, should usually
+be used here.
+
+C<$iOpts> is a numeric value containing bits that control options
+used while creating the new subkey. C<REG_OPTION_NON_VOLATILE>
+is the default. C<REG_OPTION_VOLATILE> [which is ignored on
+Windows 95] means the data stored under this key is not kept
+in a file and will not be preserved when the system reboots.
+C<REG_OPTION_BACKUP_RESTORE> [also ignored on Windows 95] means
+ignore the C<$iAccess> parameter and try to open the new key with
+the access required to backup or restore the key.
+
+C<$iAccess> is a numeric mask of bits specifying what type of
+access is desired when opening the new subkey. See C<RegOpenKeyEx()>.
+
+C<$pSecAttr> is a C<SECURITY_ATTRIBUTES> structure packed into
+a Perl string which controls whether the returned handle can be
+inherited by child processes. Normally you would pass C<[]> for
+this parameter to have C<NULL> passed to the underlying API
+indicating that the handle cannot be inherited. If not under
+Windows95, then C<$pSecAttr> also allows you to specify
+C<SECURITY_DESCRIPTOR> that controls which users will have
+what type of access to the new key -- otherwise the new key
+inherits its security from its parent key.
+
+C<$phKey> will be set to the handle to be used to access the new
+subkey if the call succeeds.
+
+C<$piDisp> will be set to either C<REG_CREATED_NEW_KEY> or
+C<REG_OPENED_EXISTING_KEY> to indicate for which reason the
+call succeeded. Can be specified as C<[]> if you don't care.
+
+If C<$phKey> and C<$piDisp> start out as integers, then they will
+probably remain unchanged if the call fails.
+
+=item RegDeleteKey
+
+=item C<RegDeleteKey( $hKey, $sSubKey )>
+
+Deletes a subkey of an open Registry key provided that the subkey
+contains no subkeys of its own [but the subkey may contain values].
+Returns a true value if successful and a false value [and sets
+C<$^E>/C<regLastError()>] on failure.
+
+C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
+a previous call].
+
+C<$sSubKey> is the name of the subkey to be deleted.
+
+=item RegDeleteValue
+
+=item C<RegDeleteValue( $hKey, $sValueName )>
+
+Deletes a value from an open Registry key. Returns a true value if
+successful and a false value [and sets C<$^E>/C<regLastError()>] on
+failure.
+
+C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
+a previous call].
+
+C<$sValueKey> is the name of the value to be deleted.
+
+=item RegEnumKey
+
+=item C<RegEnumKey( $hKey, $uIndex, $osName, $ilNameSize )>
+
+This routine is meant only for compatibility with Windows version
+3.1. Use C<RegEnumKeyEx()> instead.
+
+=item RegEnumKeyEx
+
+=item C<RegEnumKeyEx( $hKey, $uIndex, $osName, $iolName, $pNull, $osClass, $iolClass, $opftLastWrite )>
+
+Lets you enumerate the names of all of the subkeys directly under
+an open Registry key. Returns a true value if successful and a false
+value [and sets C<$^E>/C<regLastError()>] on failure.
+
+C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
+a previous call].
+
+C<$iIndex> is the sequence number of the immediate subkey that
+you want information on. Start with this value as C<0> then
+repeat the call incrementing this value each time until the
+call fails with C<$^E>/C<regLastError()> numerically equal to
+C<ERROR_NO_MORE_ITEMS>.
+
+C<$sName> will be set to the name of the subkey. Can be C<[]> if
+you don't care about the name.
+
+C<$plName> initially specifies the [minimum] buffer size to be
+allocated for C<$sName>. Will be set to the length of the subkey
+name if the requested subkey exists even if C<$sName> isn't
+successfully set to the subkey name. See L<Buffer sizes> for
+more information.
+
+C<$pNull> is reserved for future used and should be passed as C<[]>.
+
+C<$sClass> will be set to the class name for the subkey. Can be
+C<[]> if you don't care about the class.
+
+C<$plClass> initially specifies the [minimum] buffer size to be
+allocated for C<$sClass> and will be set to the length of the
+subkey class name if the requested subkey exists. See L<Buffer
+sizes> for more information.
+
+C<$pftLastWrite> will be set to a C<FILETIME> structure packed
+into a Perl string and indicating when the subkey was last changed.
+Can be C<[]>.
+
+You may omit both C<$plName> and C<$plClass> to get the same effect
+as passing in C<[]> for each of them.
+
+=item RegEnumValue
+
+=item C<RegEnumValue( $hKey, $uIndex, $osValName, $iolValName, $pNull, $ouType, $opValData, $iolValData )>
+
+Lets you enumerate the names of all of the values contained in an
+open Registry key. Returns a true value if successful and a false
+value [and sets C<$^E>/C<regLastError()>] on failure.
+
+C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
+a previous call].
+
+C<$iIndex> is the sequence number of the value that you want
+information on. Start with this value as C<0> then repeat the
+call incrementing this value each time until the call fails with
+C<ERROR_NO_MORE_ITEMS>.
+
+C<$sValName> will be set to the name of the value. Can be C<[]>
+if you don't care about the name.
+
+C<$plValName> initially specifies the [minimum] buffer size to be
+allocated for C<$sValName>. Will be set to the length of the value
+name if the requested value exists even if C<$sValName> isn't
+successfully set to the value name. See L<Buffer sizes> for
+more information.
+
+C<$pNull> is reserved for future used and should be passed as C<[]>.
+
+C<$piType> will be set to the type of data stored in the value data.
+If the call succeeds, it will be set to a C<REG_*> value unless
+passed in as C<[]>.
+
+C<$pValData> will be set to the data [packed into a Perl string]
+that is stored in the requested value. Can be C<[]> if you don't
+care about the value data.
+
+C<$plValData> initially specifies the [minimum] buffer size to be
+allocated for C<$sValData> and will be set to the length of the
+value data if the requested value exists. See L<Buffer sizes> for
+more information.
+
+You may omit both C<$plValName> and C<$plValData> to get the same
+effect as passing in C<[]> for each of them.
+
+=item RegFlushKey
+
+=item C<RegFlushKey( $hKey )>
+
+Forces the data stored under an open Registry key to be flushed
+to the disk file where the data is preserved between reboots.
+Forced flushing is not guaranteed to be efficient so this routine
+should almost never be called. Returns a true value if successful
+and a false value [and sets C<$^E>/C<regLastError()>] on failure.
+
+C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
+a previous call].
+
+=item RegGetKeySecurity
+
+=item C<RegGetKeySecurity( $hKey, $uSecInfo, $opSecDesc, $iolSecDesc )>
+
+Retrieves one of the C<SECURITY_DESCRIPTOR> structures describing
+part of the security for an open Registry key. Returns a true value
+if successful and a false value [and sets C<$^E>/C<regLastError()>]
+on failure.
+
+C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
+a previous call].
+
+C<$iSecInfo> is a numeric C<SECURITY_INFORMATION> value that
+specifies which parts of the C<SECURITY_DESCRIPTOR> structure
+to retrieve. Should be C<OWNER_SECURITY_INFORMATION>,
+C<GROUP_SECURITY_INFORMATION>, C<DACL_SECURITY_INFORMATION>, or
+or C<SACL_SECURITY_INFORMATION> or two or more of these bits
+combined using C<|>.
+
+C<$pSecDesc> will be set to the requested C<SECURITY_DESCRIPTOR>
+structure [packed into a Perl string].
+
+C<$plSecDesc> initially specifies the [minimum] buffer size to be
+allocated for C<$sSecDesc> and will be set to the length of the
+security descriptor. See L<Buffer sizes> for more information.
+You may omit this parameter to get the same effect as passing in
+C<[]> for it.
+
+=item regLastError
+
+=item C<$svError= regLastError();>
+
+=item C<regLastError( $uError );>
+
+Returns the last error encountered by a routine from this module.
+It is just like C<$^E> except it isn't changed by anything except
+routines from this module. Ideally you could just use C<$^E>, but
+current versions of Perl often overwrite C<$^E> before you get a
+chance to check it and really old versions of Perl don't really
+support C<$^E> under Win32.
+
+Just like C<$^E>, in a numeric context C<regLastError()> returns
+the numeric error value while in a string context it returns a
+text description of the error [actually it returns a Perl scalar
+that contains both values so C<$x= regLastError()> causes C<$x>
+to give different values in string vs. numeric contexts]. On old
+versions of Perl where C<$^E> isn't tied to C<GetLastError()>,
+C<regLastError> simply returns the number of the error and you'll
+need to use <Win32::FormatMessage> to get the error string.
+
+The last form sets the error returned by future calls to
+C<regLastError()> and should not be used often. C<$uError> must
+be a numeric error code. Also returns the dual-valued version
+of C<$uError>.
+
+=item RegLoadKey
+
+=item C<RegLoadKey( $hKey, $sSubKey, $sFileName )>
+
+Loads a hive file. That is, it creates a new subkey in the
+Registry and associates that subkey with a disk file that contains
+a Registry hive so that the new subkey can be used to access the
+keys and values stored in that hive. Hives are usually created
+via C<RegSaveKey()>. Returns a true value if successful and a
+false value [and sets C<$^E>/C<regLastError()>] on failure.
+
+C<$hKey> is the handle to a Registry key that can have hives
+loaded to it. This must be C<HKEY_LOCAL_MACHINE>, C<HKEY_USERS>,
+or a remote version of one of these from a call to
+C<RegConnectRegistry()>.
+
+C<$sSubKey> is the name of the new subkey to created and associated
+with the hive file.
+
+C<$sFileName> is the name of the hive file to be loaded. This
+file name is interpretted relative to the
+C<%SystemRoot%/System32/config> directory on the computer where
+the C<$hKey> key resides. If C<$sFileName> is on a FAT file
+system, then its name must not have an extension.
+
+You must have the C<SE_RESTORE_NAME> privilege to use this routine.
+
+WARNING: Loading of hive files via a network share may silently
+corrupt the hive and so should not be attempted [this is a problem
+in at least some versions of the underlying API which this module
+does not try to fix or avoid]. To access a hive file located on a
+remote computer, connect to the remote computer's Registry and load
+the hive via that.
+
+=item RegNotifyChangeKeyValue
+
+=item C<RegNotifyChangeKeyValue( $hKey, $bWatchSubtree, $uNotifyFilter, $hEvent, $bAsync )>
+
+Arranges for your process to be notified when part of the Registry
+is changed. Returns a true value if successful and a false value
+[and sets C<$^E>/C<regLastError()>] on failure.
+
+C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
+a previous call] for which you wish to be notified when any changes
+are made to it.
+
+If C<$bWatchSubtree> is true, then changes to any subkey or
+descendant of C<$hKey> are also reported.
+
+C<$iNotifyFilter> controllers what types of changes are reported. It
+is a numeric value containing one or more of the following bit masks:
+
+=over
+
+=item C<REG_NOTIFY_CHANGE_NAME>
+
+Notify if a subkey is added or deleted to a monitored key.
+
+=item C<REG_NOTIFY_CHANGE_LAST_SET>
+
+Notify if a value in a monitored key is added, deleted, or modified.
+
+=item C<REG_NOTIFY_CHANGE_SECURITY>
+
+Notify if a security descriptor of a monitored key is changed.
+
+=item C<REG_NOTIFY_CHANGE_ATTRIBUTES>
+
+Notify if any attributes of a monitored key are changed [class
+name or security descriptors].
+
+=back
+
+C<$hEvent> is ignored unless C<$bAsync> is true. Otherwise, C<$hEvent>
+is a handle to a Win32 I<event> that will be signaled when changes are
+to be reported.
+
+If C<$bAsync> is true, then C<RegNotifyChangeKeyValue()> returns
+immediately and uses C<$hEvent> to notify your process of changes.
+If C<$bAsync> is false, then C<RegNotifyChangeKeyValue()> does
+not return until there is a change to be notified of.
+
+This routine does not work with Registry keys on remote computers.
+
+=item RegOpenKey
+
+=item C<RegOpenKey( $hKey, $sSubKey, $ohSubKey )>
+
+This routine is meant only for compatibility with Windows version
+3.1. Use C<RegOpenKeyEx()> instead.
+
+=item RegOpenKeyEx
+
+=item C<RegOpenKeyEx( $hKey, $sSubKey, $uOptions, $uAccess, $ohSubKey )>
+
+Opens an existing Registry key. Returns a true value if successful
+and a false value [and sets C<$^E>/C<regLastError()>] on failure.
+
+C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
+a previous call].
+
+C<$sSubKey> is the name of an existing subkey to be opened.
+Can be C<""> or C<[]> to open an additional handle to the
+key specified by C<$hKey>.
+
+C<$iOptions> is a numeric value containing bits that control options
+used while opening the subkey. There are currently no supported
+options so this parameter should be specified as C<0>.
+
+C<$iAccess> is a numeric mask of bits specifying what type of
+access is desired when opening the new subkey. Should be a
+combination of one or more of the following bit masks:
+
+=over
+
+=item C<KEY_ALL_ACCESS>
+
+ KEY_READ | KEY_WRITE | KEY_CREATE_LINK
+
+=item C<KEY_READ>
+
+ KEY_QUERY_VALUE | KEY_ENUMERATE_SUBKEYS | KEY_NOTIFY | STANDARD_RIGHTS_READ
+
+=item C<KEY_WRITE>
+
+ KEY_SET_VALUE | KEY_CREATE_SUB_KEY | STANDARD_RIGHTS_WRITE
+
+=item C<KEY_QUERY_VALUE>
+
+=item C<KEY_SET_VALUE>
+
+=item C<KEY_ENUMERATE_SUB_KEYS>
+
+=item C<KEY_CREATE_SUB_KEY>
+
+=item C<KEY_NOTIFY>
+
+Allows you to use C<RegNotifyChangeKeyValue()> on the opened key.
+
+=item C<KEY_EXECUTE>
+
+Same as C<KEY_READ>.
+
+=item C<KEY_CREATE_LINK>
+
+Gives you permission to create a symbolic link like
+C<HKEY_CLASSES_ROOT> and C<HKEY_CURRENT_USER>, though the method for
+doing so is not documented [and probably requires use of the mostly
+undocumented "native" routines, C<Nt*()> a.k.a. C<Zw*()>].
+
+=back
+
+C<$phKey> will be set to the handle to be used to access the new subkey
+if the call succeeds.
+
+=item RegQueryInfoKey
+
+=item C<RegQueryInfoKey( $hKey, $osClass, $iolClass, $pNull, $ocSubKeys, $olSubKey, $olSubClass, $ocValues, $olValName, $olValData, $olSecDesc, $opftTime )>
+
+Gets miscellaneous information about an open Registry key.
+Returns a true value if successful and a false value [and
+sets C<$^E>/C<regLastError()>] on failure.
+
+C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
+a previous call].
+
+C<$sClass> will be set to the class name for the key. Can be
+C<[]> if you don't care about the class.
+
+C<$plClass> initially specifies the [minimum] buffer size to be
+allocated for C<$sClass> and will be set to the length of the
+key's class name. See L<Buffer sizes> for more information.
+You may omit this parameter to get the same effect as passing in
+C<[]> for it.
+
+C<$pNull> is reserved for future use and should be passed as C<[]>.
+
+C<$pcSubKeys> will be set to the count of the number of subkeys
+directly under this key. Can be C<[]>.
+
+C<$plSubKey> will be set to the length of the longest subkey name.
+Can be C<[]>.
+
+C<$plSubClass> will be set to the length of the longest class name
+used with an immediate subkey of this key. Can be C<[]>.
+
+C<$pcValues> will be set to the count of the number of values in
+this key. Can be C<[]>.
+
+C<$plValName> will be set to the length of the longest value name
+in this key. Can be C<[]>.
+
+C<$plValData> will be set to the length of the longest value data
+in this key. Can be C<[]>.
+
+C<$plSecDesc> will be set to the length of this key's full security
+descriptor.
+
+C<$pftTime> will be set to a C<FILETIME> structure packed
+into a Perl string and indicating when this key was last changed.
+Can be C<[]>.
+
+=item RegQueryMultipleValues
+
+=item C<RegQueryMultipleValues( $hKey, $ioarValueEnts, $icValueEnts, $opBuffer, $iolBuffer )>
+
+Allows you to use a single call to query several values from a single
+open Registry key to maximize efficiency. Returns a true value if
+successful and a false value [and sets C<$^E>/C<regLastError()>] on
+failure.
+
+C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
+a previous call].
+
+C<$pValueEnts> should contain a list of C<VALENT> structures packed
+into a single Perl string. Each C<VALENT> structure should have
+the C<ve_valuename> entry [the first 4 bytes] pointing to a string
+containing the name of a value stored in this key. The remaining
+fields are set if the function succeeds.
+
+C<$cValueEnts> should contain the count of the number of C<VALENT>
+structures contained in C<$pValueEnts>.
+
+C<$pBuffer> will be set to the data from all of the requested values
+concatenated into a single Perl string.
+
+C<$plBuffer> initially specifies the [minimum] buffer size to be
+allocated for C<$sBuffer> and will be set to the total length of
+the data to be written to C<$sBuffer>. See L<Buffer sizes> for
+more information. You may omit this parameter to get the same
+effect as passing in C<[]> for it.
+
+Here is sample code to populate C<$pValueEnts>:
+
+ # @ValueNames= ...list of value name strings...;
+ $cValueEnts= @ValueNames;
+ $pValueEnts= pack( " p x4 x4 x4 " x $cValueEnts, @ValueNames );
+
+Here is sample code to retrieve the data type and data length
+returned in C<$pValueEnts>:
+
+ @Lengths= unpack( " x4 L x4 x4 " x $cValueEnts, $pValueEnts );
+ @Types= unpack( " x4 x4 x4 L " x $cValueEnts, $pValueEnts );
+
+Given the above, and assuming you haven't modified C<$sBuffer> since
+the call, you can also extract the value data strings from C<$sBuffer>
+by using the pointers returned in C<$pValueEnts>:
+
+ @Data= unpack( join( "", map {" x4 x4 P$_ x4 "} @Lengths ),
+ $pValueEnts );
+
+Much better is to use the lengths and extract directly from
+C<$sBuffer> using C<unpack()> [or C<substr()>]:
+
+ @Data= unpack( join("",map("P$_",@Lengths)), $sBuffer );
+
+=item RegQueryValue
+
+=item C<RegQueryValue( $hKey, $sSubKey, $osValueData, $iolValueData )>
+
+This routine is meant only for compatibility with Windows version
+3.1. Use C<RegQueryValueEx()> instead. This routine can only
+query unamed values [a.k.a. "default values"], that is, values with
+a name of C<"">.
+
+=item RegQueryValueEx
+
+=item C<RegQueryValueEx( $hKey, $sValueName, $pNull, $ouType, $opValueData, $iolValueData )>
+
+Lets you look up value data stored in an open Registry key by
+specifying the value name. Returns a true value if successful
+and a false value [and sets C<$^E>/C<regLastError()>] on failure.
+
+C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
+a previous call].
+
+C<$sValueName> is the name of the value whose data you wish to
+retrieve.
+
+C<$pNull> this parameter is reserved for future use and should be
+specified as C<[]>.
+
+C<$piType> will be set to indicate what type of data is stored in
+the named value. Will be set to a C<REG_*> value if the function
+succeeds.
+
+C<$pValueData> will be set to the value data [packed into a Perl
+string] that is stored in the named value. Can be C<[]> if you
+don't care about the value data.
+
+C<$plValueData> initially specifies the [minimum] buffer size to be
+allocated for C<$sValueData> and will be set to the size [always
+in bytes] of the data to be written to C<$sValueData>, even if
+C<$sValueData> is not successfully written to. See L<Buffer sizes>
+for more information.
+
+=item RegReplaceKey
+
+=item C<RegReplaceKey( $hKey, $sSubKey, $sNewFile, $sOldFile )>
+
+Lets you replace an entire hive when the system is next booted.
+Returns a true value if successful and a false value [and sets
+C<$^E>/C<regLastError()>] on failure.
+
+C<$hKey> is the handle to a Registry key that has hive(s)
+loaded in it. This must be C<HKEY_LOCAL_MACHINE>,
+C<HKEY_USERS>, or a remote version of one of these from
+a call to C<RegConnectRegistry()>.
+
+C<$sSubKey> is the name of the subkey of C<$hKey> whose hive
+you wish to have replaced on the next reboot.
+
+C<$sNewFile> is the name of a file that will replace the existing
+hive file when the system reboots.
+
+C<$sOldFile> is the file name to save the current hive file to
+when the system reboots.
+
+C<$sNewFile> and C<$sOldFile> are interpretted relative to the
+C<%SystemRoot%/System32/config> directory on the computer where
+the C<$hKey> key resides [I think]. If either file is [would be]
+on a FAT file system, then its name must not have an extension.
+
+You must have the C<SE_RESTORE_NAME> privilege to use this routine.
+
+=item RegRestoreKey
+
+=item C<RegRestoreKey( $hKey, $sFileName, $uFlags )>
+
+Reads in a hive file and copies its contents over an existing
+Registry tree. Returns a true value if successful and a false
+value [and sets C<$^E>/C<regLastError()>] on failure.
+
+C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
+a previous call].
+
+C<$sFileName> is the name of the hive file to be read. For each
+value and subkey in this file, a value or subkey will be added
+or replaced in C<$hKey>.
+
+C<$uFlags> is usally C<0>. It can also be C<REG_WHOLE_HIVE_VOLATILE>
+which, rather than copying the hive over the existing key,
+replaces the existing key with a temporary, memory-only Registry
+key and then copies the hive contents into it. This option only
+works if C<$hKey> is C<HKEY_LOCAL_MACHINE>, C<HKEY_USERS>, or a
+remote version of one of these from a call to C<RegConnectRegistry()>.
+
+C<RegRestoreKey> does I<not> delete values nor keys from the
+existing Registry tree when there is no corresponding value/key
+in the hive file.
+
+=item RegSaveKey
+
+=item C<RegSaveKey( $hKey, $sFileName, $pSecAttr )>
+
+Dumps any open Registry key and all of its subkeys and values into
+a new hive file. Returns a true value if successful and a false
+value [and sets C<$^E>/C<regLastError()>] on failure.
+
+C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
+a previous call].
+
+C<$sFileName> is the name of the file that the Registry tree
+should be saved to. It is interpretted relative to the
+C<%SystemRoot%/System32/config> directory on the computer where
+the C<$hKey> key resides. If C<$sFileName> is on a FAT file system,
+then it must not have an extension.
+
+C<$pSecAttr> contains a C<SECURITY_ATTRIBUTES> structure that specifies
+the permissions to be set on the new file that is created. This can
+be C<[]>.
+
+You must have the C<SE_RESTORE_NAME> privilege to use this routine.
+
+=item RegSetKeySecurity
+
+=item C<RegSetKeySecurity( $hKey, $uSecInfo, $pSecDesc )>
+
+Sets [part of] the C<SECURITY_DESCRIPTOR> structure describing part
+of the security for an open Registry key. Returns a true value if
+successful and a false value [and sets C<$^E>/C<regLastError()>] on
+failure.
+
+C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
+a previous call].
+
+C<$uSecInfo> is a numeric C<SECURITY_INFORMATION> value that
+specifies which C<SECURITY_DESCRIPTOR> structure to set. Should
+be C<OWNER_SECURITY_INFORMATION>, C<GROUP_SECURITY_INFORMATION>,
+C<DACL_SECURITY_INFORMATION>, or C<SACL_SECURITY_INFORMATION>
+or two or more of these bits combined using C<|>.
+
+C<$pSecDesc> contains the new C<SECURITY_DESCRIPTOR> structure
+packed into a Perl string.
+
+=item RegSetValue
+
+=item C<RegSetValue( $hKey, $sSubKey, $uType, $sValueData, $lValueData )>
+
+This routine is meant only for compatibility with Windows version
+3.1. Use C<RegSetValueEx()> instead. This routine can only
+set unamed values [a.k.a. "default values"].
+
+=item RegSetValueEx
+
+=item C<RegSetValueEx( $hKey, $sName, $uZero, $uType, $pData, $lData )>
+
+Adds or replaces a value in an open Registry key. Returns
+a true value if successful and a false value [and sets
+C<$^E>/C<regLastError()>] on failure.
+
+C<$hKey> is the handle to a Registry key [either C<HKEY_*> or from
+a previous call].
+
+C<$sName> is the name of the value to be set.
+
+C<$uZero> is reserved for future use and should be specified as C<0>.
+
+C<$uType> is the type of data stored in C<$pData>. It should
+be a C<REG_*> value.
+
+C<$pData> is the value data packed into a Perl string.
+
+C<$lData> is the length of the value data that is stored in C<$pData>.
+You will usually omit this parameter or pass in C<0> to have
+C<length($pData)> used. In both of these cases, if C<$iType> is
+C<REG_SZ> or C<REG_EXPAND_SZ>, C<RegSetValueEx()> will append a
+trailing C<'\0'> to the end of C<$pData> [unless there is already
+one].
+
+=item RegUnLoadKey
+
+=item C<RegUnLoadKey( $hKey, $sSubKey )>
+
+Unloads a previously loaded hive file. That is, closes the
+hive file then deletes the subkey that was providing access
+to it. Returns a true value if successful and a false value
+[and sets C<$^E>/C<regLastError()>] on failure.
+
+C<$hKey> is the handle to a Registry key that has hives
+loaded in it. This must be C<HKEY_LOCAL_MACHINE>, C<HKEY_USERS>,
+or a remote version of one of these from a call to
+C<RegConnectRegistry()>.
+
+C<$sSubKey> is the name of the subkey whose hive you wish to
+have unloaded.
+
+=item :FuncA
+
+The ASCII-specific function names.
+
+Each of these is identical to the version listed above without the
+trailing "A":
+
+ AbortSystemShutdownA InitiateSystemShutdownA
+ RegConnectRegistryA RegCreateKeyA RegCreateKeyExA
+ RegDeleteKeyA RegDeleteValueA RegEnumKeyA
+ RegEnumKeyExA RegEnumValueA RegLoadKeyA
+ RegOpenKeyA RegOpenKeyExA RegQueryInfoKeyA
+ RegQueryMultipleValuesA RegQueryValueA RegQueryValueExA
+ RegReplaceKeyA RegRestoreKeyA RegSaveKeyA
+ RegSetValueA RegSetValueExA RegUnLoadKeyA
+
+=item :FuncW
+
+The UNICODE-specific function names. These are the same as the
+versions listed above without the trailing "W" except that string
+parameters are UNICODE strings rather than ASCII strings, as
+indicated.
+
+=item AbortSystemShutdownW
+
+=item C<AbortSystemShutdownW( $swComputerName )>
+
+C<$swComputerName> is UNICODE.
+
+=item InitiateSystemShutdownW
+
+=item C<InitiateSystemShutdownW( $swComputer, $swMessage, $uTimeoutSecs, $bForce, $bReboot )>
+
+C<$swComputer> and C<$swMessage> are UNICODE.
+
+=item RegConnectRegistryW
+
+=item C<RegConnectRegistryW( $swComputer, $hRootKey, $ohKey )>
+
+C<$swComputer> is UNICODE.
+
+=item RegCreateKeyW
+
+=item C<RegCreateKeyW( $hKey, $swSubKey, $ohSubKey )>
+
+C<$swSubKey> is UNICODE.
+
+=item RegCreateKeyExW
+
+=item C<RegCreateKeyExW( $hKey, $swSubKey, $uZero, $swClass, $uOpts, $uAccess, $pSecAttr, $ohNewKey, $ouDisp )>
+
+C<$swSubKey> and C<$swClass> are UNICODE.
+
+=item RegDeleteKeyW
+
+=item C<RegDeleteKeyW( $hKey, $swSubKey )>
+
+C<$swSubKey> is UNICODE.
+
+=item RegDeleteValueW
+
+=item C<RegDeleteValueW( $hKey, $swValueName )>
+
+C<$swValueName> is UNICODE.
+
+=item RegEnumKeyW
+
+=item C<RegEnumKeyW( $hKey, $uIndex, $oswName, $ilwNameSize )>
+
+C<$oswName> is UNICODE and C<$ilwNameSize> is measured as number of
+C<WCHAR>s.
+
+=item RegEnumKeyExW
+
+=item C<RegEnumKeyExW( $hKey, $uIndex, $oswName, $iolwName, $pNull, $oswClass, $iolwClass, $opftLastWrite )>
+
+C<$swName> and C<$swClass> are UNICODE and C<$iolwName> and C<$iolwClass>
+are measured as number of C<WCHAR>s.
+
+=item RegEnumValueW
+
+=item C<RegEnumValueW( $hKey, $uIndex, $oswName, $iolwName, $pNull, $ouType, $opData, $iolData )>
+
+C<$oswName> is UNICODE and C<$iolwName> is measured as number
+of C<WCHAR>s.
+
+C<$opData> is UNICODE if C<$piType> is C<REG_SZ>, C<REG_EXPAND_SZ>,
+or C<REG_MULTI_SZ>. Note that C<$iolData> is measured as number
+of bytes even in these cases.
+
+=item RegLoadKeyW
+
+=item C<RegLoadKeyW( $hKey, $swSubKey, $swFileName )>
+
+C<$swSubKey> and C<$swFileName> are UNICODE.
+
+=item RegOpenKeyW
+
+=item C<RegOpenKeyW( $hKey, $swSubKey, $ohSubKey )>
+
+C<$swSubKey> is UNICODE.
+
+=item RegOpenKeyExW
+
+=item C<RegOpenKeyExW( $hKey, $swSubKey, $uOptions, $uAccess, $ohSubKey )>
+
+C<$swSubKey> is UNICODE.
+
+=item RegQueryInfoKeyW
+
+=item C<RegQueryInfoKeyW( $hKey, $oswClass, $iolwClass, $pNull, $ocSubKeys, $olwSubKey, $olwSubClass, $ocValues, $olwValName, $olValData, $olSecDesc, $opftTime )>
+
+C<$swClass> is UNICODE. C<$iolwClass>, C<$olwSubKey>, C<$olwSubClass>,
+and C<$olwValName> are measured as number of C<WCHAR>s. Note that
+C<$olValData> is measured as number of bytes.
+
+=item RegQueryMultipleValuesW
+
+=item C<RegQueryMultipleValuesW( $hKey, $ioarValueEnts, $icValueEnts, $opBuffer, $iolBuffer )>
+
+The C<ve_valuename> fields of the C<VALENT> [actually C<VALENTW>]
+structures in C<$ioarValueEnts> are UNICODE. Values of type C<REG_SZ>,
+C<REG_EXPAND_SZ>, and C<REG_MULTI_SZ> are written to C<$opBuffer>
+in UNICODE. Note that C<$iolBuffer> and the C<ve_valuelen> fields
+of the C<VALENT> [C<VALENTW>] structures are measured as number of
+bytes.
+
+=item RegQueryValueW
+
+=item C<RegQueryValueW( $hKey, $swSubKey, $oswValueData, $iolValueData )>
+
+C<$swSubKey> and C<$oswValueData> are UNICODE. Note that
+C<$iolValueData> is measured as number of bytes.
+
+=item RegQueryValueExW
+
+=item C<RegQueryValueExW( $hKey, $swName, $pNull, $ouType, $opData, $iolData )>
+
+C<$swName> is UNICODE.
+
+C<$opData> is UNICODE if C<$ouType> is C<REG_SZ>, C<REG_EXPAND_SZ>,
+or C<REG_MULTI_SZ>. Note that C<$iolData> is measured as number of
+bytes even in these cases.
+
+=item RegReplaceKeyW
+
+=item C<RegReplaceKeyW( $hKey, $swSubKey, $swNewFile, $swOldFile )>
+
+C<$swSubKey>, C<$swNewFile>, and C<$swOldFile> are UNICODE.
+
+=item RegRestoreKeyW
+
+=item C<RegRestoreKeyW( $hKey, $swFileName, $uFlags )>
+
+C<$swFileName> is UNICODE.
+
+=item RegSaveKeyW
+
+=item C<RegSaveKeyW( $hKey, $swFileName, $pSecAttr )>
+
+C<$swFileName> is UNICODE.
+
+=item RegSetValueW
+
+=item C<RegSetValueW( $hKey, $swSubKey, $uType, $swValueData, $lValueData )>
+
+C<$swSubKey> and C<$swValueData> are UNICODE. Note that
+C<$lValueData> is measured as number of bytes even though
+C<$swValueData> is always UNICODE.
+
+=item RegSetValueExW
+
+=item C<RegSetValueExW( $hKey, $swName, $uZero, $uType, $pData, $lData )>
+
+C<$swName> is UNICODE.
+
+C<$pData> is UNICODE if C<$uType> is C<REG_SZ>, C<REG_EXPAND_SZ>,
+or C<REG_MULTI_SZ>. Note that C<$lData> is measured as number of
+bytes even in these cases.
+
+=item RegUnLoadKeyW
+
+=item C<RegUnLoadKeyW( $hKey, $swSubKey )>
+
+C<$swSubKey> is UNICODE.
+
+=item :HKEY_
+
+All C<HKEY_*> constants:
+
+ HKEY_CLASSES_ROOT HKEY_CURRENT_CONFIG HKEY_CURRENT_USER
+ HKEY_DYN_DATA HKEY_LOCAL_MACHINE HKEY_PERFORMANCE_DATA
+ HKEY_USERS
+
+=item :KEY_
+
+All C<KEY_*> constants:
+
+ KEY_QUERY_VALUE KEY_SET_VALUE KEY_CREATE_SUB_KEY
+ KEY_ENUMERATE_SUB_KEYS KEY_NOTIFY KEY_CREATE_LINK
+ KEY_READ KEY_WRITE KEY_EXECUTE
+ KEY_ALL_ACCESS
+
+=item :REG_
+
+All C<REG_*> constants:
+
+ REG_CREATED_NEW_KEY REG_OPENED_EXISTING_KEY
+
+ REG_LEGAL_CHANGE_FILTER REG_NOTIFY_CHANGE_ATTRIBUTES
+ REG_NOTIFY_CHANGE_NAME REG_NOTIFY_CHANGE_LAST_SET
+ REG_NOTIFY_CHANGE_SECURITY REG_LEGAL_OPTION
+
+ REG_OPTION_BACKUP_RESTORE REG_OPTION_CREATE_LINK
+ REG_OPTION_NON_VOLATILE REG_OPTION_OPEN_LINK
+ REG_OPTION_RESERVED REG_OPTION_VOLATILE
+
+ REG_WHOLE_HIVE_VOLATILE REG_REFRESH_HIVE
+ REG_NO_LAZY_FLUSH
+
+ REG_NONE REG_SZ
+ REG_EXPAND_SZ REG_BINARY
+ REG_DWORD REG_DWORD_LITTLE_ENDIAN
+ REG_DWORD_BIG_ENDIAN REG_LINK
+ REG_MULTI_SZ REG_RESOURCE_LIST
+ REG_FULL_RESOURCE_DESCRIPTOR REG_RESOURCE_REQUIREMENTS_LIST
+
+=item :ALL
+
+All of the above.
+
+=item :SE_
+
+The strings for the following privilege names:
+
+ SE_ASSIGNPRIMARYTOKEN_NAME SE_AUDIT_NAME
+ SE_BACKUP_NAME SE_CHANGE_NOTIFY_NAME
+ SE_CREATE_PAGEFILE_NAME SE_CREATE_PERMANENT_NAME
+ SE_CREATE_TOKEN_NAME SE_DEBUG_NAME
+ SE_INCREASE_QUOTA_NAME SE_INC_BASE_PRIORITY_NAME
+ SE_LOAD_DRIVER_NAME SE_LOCK_MEMORY_NAME
+ SE_MACHINE_ACCOUNT_NAME SE_PROF_SINGLE_PROCESS_NAME
+ SE_REMOTE_SHUTDOWN_NAME SE_RESTORE_NAME
+ SE_SECURITY_NAME SE_SHUTDOWN_NAME
+ SE_SYSTEMTIME_NAME SE_SYSTEM_ENVIRONMENT_NAME
+ SE_SYSTEM_PROFILE_NAME SE_TAKE_OWNERSHIP_NAME
+ SE_TCB_NAME SE_UNSOLICITED_INPUT_NAME
+
+It can be difficult to successfully build this module in a way
+that makes these constants available. So some builds of this
+module may not make them available. For such builds, trying
+to export any of these constants will cause a fatal error.
+For this reason, none of these symbols are currently included
+in the C<":ALL"> grouping.
+
+=back
+
+=back
+
+=head2 The Win32API:: heirarchy
+
+This and the other Win32API:: modules are meant to expose the
+nearly raw API calls so they can be used from Perl code in any
+way they might be used from C code. This provides the following
+advantages:
+
+=over
+
+=item Many modules can be written by people that don't have a C compiler.
+
+=item Encourages more module code to be written in Perl [not C].
+
+Perl code is often much easier to inspect, debug, customize, and
+enhance than XS code.
+
+=item Allows those already familiar with the Win32 API to get
+off to a quick start.
+
+=item Provides an interactive tool for exploring even obscure
+details of the Win32 API.
+
+It can be very useful to interactively explore ad-hoc calls into
+parts of the Win32 API using:
+
+ perl -de 0
+
+=item Ensures that native Win32 data structures can be used.
+
+This allows maximum efficiency. It also allows data from one
+module [for example, time or security information from the
+C<Win32API::Registry> or C<Win32API::File> modules] to be used
+with other modules [for example, C<Win32API::Time> and
+C<Win32API::SecDesc>].
+
+=item Provides a single version of the XS interface to each API
+call where improvements can be collected.
+
+=back
+
+=head2 Buffer sizes
+
+For each parameter that specifies a buffer size, a value of C<0>
+can be passed. For parameter that are pointers to buffer sizes,
+you can also pass in C<NULL> by specifying an empty list reference,
+C<[]>. Both of these cases will ensure that the variable has
+I<some> buffer space allocated to it and pass in that buffer's
+allocated size. Many of the calls indicate, via C<ERROR_MORE_DATA>,
+that the buffer size was not sufficient and the F<Registry.xs>
+code will automatically enlarge the buffer to the required size
+and repeat the call.
+
+Numeric buffer sizes are used as minimum initial sizes for the
+buffers. The larger of this size and the size of space already
+allocated to the scalar will be passed to the underlying routine.
+If that size was insufficient, and the underlying call provides
+an easy method for determining the needed buffer size, then the
+buffer will be enlarged and the call repeated as above.
+
+The underlying calls define buffer size parameter as unsigned, so
+negative buffer sizes are treated as very large positive buffer
+sizes which usually cause C<malloc()> to fail.
+
+To force the F<Registry.xs> code to pass in a specific value for
+a buffer size, preceed the size with an equals sign via C<"=".>.
+Buffer sizes that are passed in as strings starting with an equals
+sign will have the equal sign stripped and the remainder of the string
+interpretted as a number [via C's C<strtoul()> using only base 10]
+which will be passed to the underlying routine [even if the allocated
+buffer is actually larger]. The F<Registry.xs> code will enlarge the
+buffer to the specified size, if needed, but will not enlarge the
+buffer based on the underlying routine requesting more space.
+
+Some Reg*() calls may not currently set the buffer size when they
+return C<ERROR_MORE_DATA>. But some that are not documented as
+doing so, currently do so anyway. So the code assumes that any
+routine I<might> do this and resizes any buffers and repeats the
+call. We hope that eventually all routines will provide this
+feature.
+
+When you use C<[]> for a buffer size, you can still find the
+length of the data returned by using C<length($buffer)>. Note
+that this length will be in bytes while a few of the buffer
+sizes would have been in units of wide characters.
+
+Note that the RegQueryValueEx*() and RegEnumValue*() calls
+will trim the trailing C<'\0'> [if present] from the returned data
+values of type C<REG_SZ> or C<REG_EXPAND_SZ> but only if the
+value data length parameter is omitted [or specified as C<[]>].
+
+The RegSetValueEx*() calls will add a trailing C<'\0'> [if
+missing] to the supplied data values of type C<REG_SZ> and
+C<REG_EXPAND_SZ> but only if the value data length parameter
+is omitted [or specified as C<0>].
+
+=head2 Hungarian Notation
+
+The following abbreviations are used at the start of each parameter
+name to hint at aspects of how the parameter is used. The prefix
+is always in lower case and followed by a capital letter that starts
+the descriptive part of the parameter name. Several of the following
+abbreviations can be combined into a single prefix.
+
+Probably not all of these prefix notations are used by this module.
+This document section may be included in any C<Win32API> module and
+so covers some notations not used by this specific module.
+
+=over
+
+=item s
+
+A string. In C, a C<'\0'>-terminated C<char *>. In Perl, just a
+string except that it will be truncated at the first C<"\0">, if
+it contains one.
+
+=item sw
+
+A wide [UNICODE] string. In C, a C<L'\0'>-terminated C<WCHAR *>.
+In Perl, a string that contains UNICODE data. You can convert a
+string to UNICODE in Perl via:
+
+ $string= "This is an example string";
+ $unicode= pack( "S*", unpack("C*",$string), 0 );
+
+Note how C<, 0> above causes an explicit C<L'\0'> to be added since
+Perl's implicit C<'\0'> that it puts after each of its strings is not
+wide enough to terminate a UNICODE string. So UNICODE strings are
+different than regular strings in that the Perl version of a regular
+string will not include the trialing C<'\0'> while the Perl version
+of a UNICODE string must include the trailing C<L'\0'>.
+
+If a UNICODE string contains no non-ASCII characters, then you
+can convert it back into a normal string via:
+
+ $string= pack( "C*", unpack("S*",$unicode) );
+ $string =~ s/\0$//;
+
+=item p
+
+A pointer to some buffer [usually containing some C<struct>]. In C,
+a C<void *> or some other pointer type. In Perl, a string that is
+usually manipulated using C<pack> and C<unpack>. The "p" is usually
+followed by more prefix character(s) to indicate what type of data is
+stored in the bufffer.
+
+=item a
+
+A packed array. In C, an array [usually of C<struct>s]. In Perl, a
+string containing the packed data. The "a" is usually followed by
+more prefix character(s) to indicate the data type of the elements.
+
+These packed arrays are also called "vectors" in places to avoid
+confusion with Perl arrays.
+
+=item n
+
+A generic number. In C, any of the integer or floating point data
+types. In Perl, a number; either an integer, unsigned, or double
+[IV, UV, or NV, respectively]. Usually an integer.
+
+=item iv
+
+A signed integral value. In C, any of the signed integer data types.
+In Perl, an integer [IV].
+
+=item u
+
+An unsigned integral value. In C, any of the unsigned integer data
+types. In Perl, an unsigned integer [UV].
+
+=item d
+
+A floating-point number. In C, a C<float> or C<double> or, perhaps,
+a C<long double>. In Perl, a double-precision floating-point number
+[NV].
+
+=item b
+
+A Boolean value. In C, any integer data type, though usually via
+a type alias of C<bool> or C<BOOL>, containing either a 0 [false] or
+non-zero [true] value. In Perl, a scalar containing a Boolean value
+[C<0>, C<"">, or C<undef> for "false" and anything else for "true"].
+
+=item c
+
+A count of items. In C, any integer data type. In Perl, an unsigned
+integer [UV]. Usually used in conjunction with a "vector" parameter
+[see L</a> above] to indicate the number of elements.
+
+=item l
+
+A length [in bytes]. In C, any integer data type. In Perl, an
+unsigned integer [UV]. Usually used in conjunction with a "string"
+or "pointer" parameter [see L</s> and L</p> above] to indicate the
+buffer size or the size of the value stored in the buffer.
+
+For strings, there is no general rule as to whether the trailing
+C<'\0'> is included in such sizes. For this reason, the C<Win32API>
+modules follow the Perl rule of always allocating one extra byte
+and reporting buffer sizes as being one smaller than allocated in
+case the C<'\0'> is not included in the size.
+
+=item lw
+
+A length measured as number of UNICODE characters. In C, a count
+of C<WCHAR>s. In Perl, an unsigned integer [UV] counting "shorts"
+[see "s" and "S" in C<pack> and C<unpack>].
+
+For UNICODE strings, the trailing C<L'\0'> may or may not be
+included in a length so, again, we always allocate extra room
+for one and don't report that extra space.
+
+=item h
+
+A handle. In C, a C<HANDLE> or more-specific handle data type.
+In Perl, an unsigned integer [UV]. In C, these handles are often
+actually some type of pointer, but Perl just treats them as opaque
+numbers, as it should. This prefix is also used for other pointers
+that are treated as integers in Perl code.
+
+=item r
+
+A record. In C, almost always a C<struct> or perhaps C<union>. Note
+that C C<struct>s are rarely passed by value so the "r" is almost
+always preceeded by a "p" or "a" [see L</p> and L</a> above]. For
+the very rare unadorned "r", Perl stores the record in the same way
+as a "pr", that is, in a string. For the very rare case where Perl
+explicitly stores a pointer to the C<struct> rather than storing the
+C<struct> directly in a Perl string, the prefix "pp" or "ppr" or even
+"par" is used.
+
+=item sv
+
+=item rv
+
+=item hv
+
+=item av
+
+=item cv
+
+A Perl data type. Respectively, a scalar value [SV], a reference
+[RV] [usually to a scalar], a hash [HV], a Perl array [AV], or a Perl
+code reference [PVCV]. For the "hv", "av", and "cv" prefixes, a
+leading "rv" is usually assumed. For a parameter to an XS subroutine,
+a prefix of "sv" means the parameter is a scalar and so may be a string
+or a number [or C<undef>] or even both at the same time. So "sv"
+doesn't imply a leading "rv".
+
+=item Input or Output
+
+Whether a parameter is for input data, output data, or both is usually
+not reflected by the data type prefix. In cases where this is not
+obvious nor reflected in the parameter name proper, we may use the
+following in front of the data type prefix.
+
+=over
+
+=item i
+
+An input parameter given to the API [usually omitted].
+
+=item o
+
+An output-only parameter taken from the API. You should not get a
+warning if such a parameter is C<undef> when you pass it into the
+function. You should get an error if such a parameter is read-only.
+You can [usually] pass in C<[]> for such a parameter to have the
+parameter silently ignored.
+
+The output may be written directly into the Perl variable passed
+to the subroutine, the same way the buffer parameter to Perl's
+C<sysread()>. This method is often avoided in Perl because
+the call then lacks any visual cue that some parameters are being
+overwritten. But this method closely matches the C API which is
+what we are trying to do.
+
+=item io
+
+Input given to the API then overwritten with output taken from the
+API. You should get a warning [if B<-w> is in effect] if such a
+parameter is C<undef> when you pass it into the function [unless it
+is a buffer or buffer length parameter]. If the value is read-only,
+then [for most parameters] the output is silently not written. This
+is because it is often convenient to pass in read-only constants for
+many such parameters. You can also usually pass in C<[]> for such
+parameters.
+
+=back
+
+=item pp
+
+=item ppr
+
+=item par
+
+=item pap
+
+These are just unusual combinations of prefix characters described above.
+
+For each, a pointer is stored in a [4-byte] Perl string. You can
+usually use C<unpack "P"> to access the real data from Perl.
+
+For "ppr" [and often for "pp"], the pointer points directly at a
+C C<struct>. For "par", the pointer points to the first element
+of a C [packed] array of C<struct>s. For "pap", the pointer points
+to a C [packed] array of pointers to other things.
+
+=item ap
+
+Here we have a list of pointers packed into a single Perl string.
+
+=back
+
+
+=head1 BUGS
+
+The old ActiveState ports of Perl for Win32 [but not, ActivePerl, the
+ActiveState distributions of standard Perl 5.004 and beyond] do not support
+the tools for building extensions and so do not support this extension.
+
+No routines are provided for using the data returned in the C<FILETIME>
+buffers. Those are in the C<Win32API::Time> module.
+
+No routines are provided for dealing with UNICODE data effectively.
+See L</:FuncW> above for some simple-minded UNICODE methods.
+
+Parts of the module test will fail if used on a version of Perl
+that does not yet set C<$^E> based on C<GetLastError()>.
+
+On NT 4.0 [at least], the RegEnum*() calls do not set the required
+buffer sizes when returning C<ERROR_MORE_DATA> so this module will
+not grow the buffers in such cases. C<Win32::TieRegistry> overcomes
+this by using values from C<RegQueryInfoKey()> for buffer sizes in
+RegEnum* calls.
+
+On NT 4.0 [at least], C<RegQueryInfoKey()> on C<HKEY_PERFORMANCE_DATA>
+never succeeds. Also, C<RegQueryValueEx()> on C<HKEY_PERFORMANCE_DATA>
+never returns the required buffer size. To access C<HKEY_PERFORMANCE_DATA>
+you will need to keep growing the data buffer until the call succeeds.
+
+Because C<goto &subroutine> seems to be buggy under Win32 Perl,
+it is not used in the stubs in F<Registry.pm>.
+
+=head1 AUTHOR
+
+Tye McQueen, tye@metronet.com, http://www.metronet.com/~tye/.
+
+=head1 SEE ALSO
+
+=over
+
+=item L<Win32::TieRegistry>
+
+=item L<Win32::Registry>
+
+=back
+
+=cut
diff --git a/Master/tlpkg/tlperl/lib/Win32API/Registry/cRegistry.pc b/Master/tlpkg/tlperl/lib/Win32API/Registry/cRegistry.pc
new file mode 100644
index 00000000000..9659d0c4361
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Win32API/Registry/cRegistry.pc
@@ -0,0 +1,87 @@
+# Generated by cRegistry_pc.cxx.
+# Package Win32API::Registry with options:
+# CPLUSPLUS => q[1]
+# IFDEF => q[ /^SE_/ ? '__cplusplus' : /REG_/ ]
+# IMPORT_LIST => [q[/._/], q[!/[a-z]/]]
+# VALUES => { KEY_DELETE=>q[DELETE], KEY_READ_CONTROL=>q[READ_CONTROL], KEY_WRITE_OWNER=>q[WRITE_OWNER], KEY_SYNCHRONIZE=>q[SYNCHRONIZE], KEY_WRITE_DAC=>q[WRITE_DAC] }
+# WRITE_PERL => q[1]
+# Perl files eval'd:
+# Registry.pm => last if /^\s*(bootstrap|XSLoader::load)\b/
+# C files included:
+# Registry.xs => last if m#/[/*]\s*CONSTS_DEFINED\b|^\s*MODULE\b#
+sub HKEY_CLASSES_ROOT () { 0x80000000 }
+sub HKEY_CURRENT_CONFIG () { 0x80000005 }
+sub HKEY_CURRENT_USER () { 0x80000001 }
+sub HKEY_DYN_DATA () { 0x80000006 }
+sub HKEY_LOCAL_MACHINE () { 0x80000002 }
+sub HKEY_PERFORMANCE_DATA () { 0x80000004 }
+sub HKEY_USERS () { 0x80000003 }
+sub KEY_ALL_ACCESS () { 983103 }
+sub KEY_CREATE_LINK () { 32 }
+sub KEY_CREATE_SUB_KEY () { 4 }
+sub KEY_DELETE () { 65536 }
+sub KEY_ENUMERATE_SUB_KEYS () { 8 }
+sub KEY_EXECUTE () { 131097 }
+sub KEY_NOTIFY () { 16 }
+sub KEY_QUERY_VALUE () { 1 }
+sub KEY_READ () { 131097 }
+sub KEY_READ_CONTROL () { 131072 }
+sub KEY_SET_VALUE () { 2 }
+sub KEY_SYNCHRONIZE () { 1048576 }
+sub KEY_WRITE () { 131078 }
+sub KEY_WRITE_DAC () { 262144 }
+sub KEY_WRITE_OWNER () { 524288 }
+sub REG_BINARY () { 3 }
+sub REG_CREATED_NEW_KEY () { 1 }
+sub REG_DWORD () { 4 }
+sub REG_DWORD_BIG_ENDIAN () { 5 }
+sub REG_DWORD_LITTLE_ENDIAN () { 4 }
+sub REG_EXPAND_SZ () { 2 }
+sub REG_FULL_RESOURCE_DESCRIPTOR () { 9 }
+sub REG_LEGAL_CHANGE_FILTER () { 15 }
+sub REG_LEGAL_OPTION () { 15 }
+sub REG_LINK () { 6 }
+sub REG_MULTI_SZ () { 7 }
+sub REG_NONE () { 0 }
+sub REG_NOTIFY_CHANGE_ATTRIBUTES () { 2 }
+sub REG_NOTIFY_CHANGE_LAST_SET () { 4 }
+sub REG_NOTIFY_CHANGE_NAME () { 1 }
+sub REG_NOTIFY_CHANGE_SECURITY () { 8 }
+sub REG_NO_LAZY_FLUSH () { 4 }
+sub REG_OPENED_EXISTING_KEY () { 2 }
+sub REG_OPTION_BACKUP_RESTORE () { 4 }
+sub REG_OPTION_CREATE_LINK () { 2 }
+sub REG_OPTION_NON_VOLATILE () { 0 }
+sub REG_OPTION_OPEN_LINK () { 8 }
+sub REG_OPTION_RESERVED () { 0 }
+sub REG_OPTION_VOLATILE () { 1 }
+sub REG_REFRESH_HIVE () { 2 }
+sub REG_RESOURCE_LIST () { 8 }
+sub REG_RESOURCE_REQUIREMENTS_LIST () { 10 }
+sub REG_SZ () { 1 }
+sub REG_WHOLE_HIVE_VOLATILE () { 1 }
+sub SE_ASSIGNPRIMARYTOKEN_NAME () { 'SeAssignPrimaryTokenPrivilege' }
+sub SE_AUDIT_NAME () { 'SeAuditPrivilege' }
+sub SE_BACKUP_NAME () { 'SeBackupPrivilege' }
+sub SE_CHANGE_NOTIFY_NAME () { 'SeChangeNotifyPrivilege' }
+sub SE_CREATE_PAGEFILE_NAME () { 'SeCreatePagefilePrivilege' }
+sub SE_CREATE_PERMANENT_NAME () { 'SeCreatePermanentPrivilege' }
+sub SE_CREATE_TOKEN_NAME () { 'SeCreateTokenPrivilege' }
+sub SE_DEBUG_NAME () { 'SeDebugPrivilege' }
+sub SE_INCREASE_QUOTA_NAME () { 'SeIncreaseQuotaPrivilege' }
+sub SE_INC_BASE_PRIORITY_NAME () { 'SeIncreaseBasePriorityPrivilege' }
+sub SE_LOAD_DRIVER_NAME () { 'SeLoadDriverPrivilege' }
+sub SE_LOCK_MEMORY_NAME () { 'SeLockMemoryPrivilege' }
+sub SE_MACHINE_ACCOUNT_NAME () { 'SeMachineAccountPrivilege' }
+sub SE_PROF_SINGLE_PROCESS_NAME () { 'SeProfileSingleProcessPrivilege' }
+sub SE_REMOTE_SHUTDOWN_NAME () { 'SeRemoteShutdownPrivilege' }
+sub SE_RESTORE_NAME () { 'SeRestorePrivilege' }
+sub SE_SECURITY_NAME () { 'SeSecurityPrivilege' }
+sub SE_SHUTDOWN_NAME () { 'SeShutdownPrivilege' }
+sub SE_SYSTEMTIME_NAME () { 'SeSystemtimePrivilege' }
+sub SE_SYSTEM_ENVIRONMENT_NAME () { 'SeSystemEnvironmentPrivilege' }
+sub SE_SYSTEM_PROFILE_NAME () { 'SeSystemProfilePrivilege' }
+sub SE_TAKE_OWNERSHIP_NAME () { 'SeTakeOwnershipPrivilege' }
+sub SE_TCB_NAME () { 'SeTcbPrivilege' }
+sub SE_UNSOLICITED_INPUT_NAME () { 'SeUnsolicitedInputPrivilege' }
+1;