cpan/Win32API-File/File.pm

   1 # File.pm -- Low-level access to Win32 file/dir functions/constants.
   2
   3 package Win32API::File;
   4
   5 use strict;
   6 use integer;
   7 use Carp;
   8 use Config qw( %Config );
   9 use Fcntl qw( O_RDONLY O_RDWR O_WRONLY O_APPEND O_BINARY O_TEXT );
  10 use vars qw( $VERSION @ISA );
  11 use vars qw( @EXPORT @EXPORT_OK @EXPORT_FAIL %EXPORT_TAGS );
  12
  13 $VERSION= '0.1201';
  14
  15 use base qw( Exporter DynaLoader Tie::Handle IO::File );
  16
  17 # Math::BigInt optimizations courtesy of Tels
  18 my $_64BITINT;
  19 BEGIN {
  20     $_64BITINT = defined($Config{use64bitint}) &&
  21                  ($Config{use64bitint} eq 'define');
  22
  23     require Math::BigInt unless $_64BITINT;
  24 }
  25
  26 my $THIRTY_TWO = $_64BITINT ? 32 : Math::BigInt->new(32);
  27
  28 my $FFFFFFFF   = $_64BITINT ? 0xFFFFFFFF : Math::BigInt->new(0xFFFFFFFF);
  29
  30 @EXPORT= qw();
  31 %EXPORT_TAGS= (
  32     Func =>     [qw(            attrLetsToBits          createFile
  33         fileConstant            fileLastError           getLogicalDrives
  34         CloseHandle             CopyFile                CreateFile
  35         DefineDosDevice         DeleteFile              DeviceIoControl
  36         FdGetOsFHandle          GetDriveType            GetFileAttributes               GetFileType
  37         GetHandleInformation    GetLogicalDrives        GetLogicalDriveStrings
  38         GetOsFHandle            GetVolumeInformation    IsRecognizedPartition
  39         IsContainerPartition    MoveFile                MoveFileEx
  40         OsFHandleOpen           OsFHandleOpenFd         QueryDosDevice
  41         ReadFile                SetErrorMode            SetFilePointer
  42         SetHandleInformation    WriteFile               GetFileSize
  43         getFileSize             setFilePointer          GetOverlappedResult)],
  44     FuncA =>    [qw(
  45         CopyFileA               CreateFileA             DefineDosDeviceA
  46         DeleteFileA             GetDriveTypeA           GetFileAttributesA              GetLogicalDriveStringsA
  47         GetVolumeInformationA   MoveFileA               MoveFileExA
  48         QueryDosDeviceA )],
  49     FuncW =>    [qw(
  50         CopyFileW               CreateFileW             DefineDosDeviceW
  51         DeleteFileW             GetDriveTypeW           GetFileAttributesW              GetLogicalDriveStringsW
  52         GetVolumeInformationW   MoveFileW               MoveFileExW
  53         QueryDosDeviceW )],
  54     Misc =>             [qw(
  55         CREATE_ALWAYS           CREATE_NEW              FILE_BEGIN
  56         FILE_CURRENT            FILE_END                INVALID_HANDLE_VALUE
  57         OPEN_ALWAYS             OPEN_EXISTING           TRUNCATE_EXISTING )],
  58     DDD_ =>     [qw(
  59         DDD_EXACT_MATCH_ON_REMOVE                       DDD_RAW_TARGET_PATH
  60         DDD_REMOVE_DEFINITION )],
  61     DRIVE_ =>   [qw(
  62         DRIVE_UNKNOWN           DRIVE_NO_ROOT_DIR       DRIVE_REMOVABLE
  63         DRIVE_FIXED             DRIVE_REMOTE            DRIVE_CDROM
  64         DRIVE_RAMDISK )],
  65     FILE_ =>    [qw(
  66         FILE_READ_DATA                  FILE_LIST_DIRECTORY
  67         FILE_WRITE_DATA                 FILE_ADD_FILE
  68         FILE_APPEND_DATA                FILE_ADD_SUBDIRECTORY
  69         FILE_CREATE_PIPE_INSTANCE       FILE_READ_EA
  70         FILE_WRITE_EA                   FILE_EXECUTE
  71         FILE_TRAVERSE                   FILE_DELETE_CHILD
  72         FILE_READ_ATTRIBUTES            FILE_WRITE_ATTRIBUTES
  73         FILE_ALL_ACCESS                 FILE_GENERIC_READ
  74         FILE_GENERIC_WRITE              FILE_GENERIC_EXECUTE )],
  75     FILE_ATTRIBUTE_ =>  [qw(
  76     INVALID_FILE_ATTRIBUTES
  77     FILE_ATTRIBUTE_DEVICE        FILE_ATTRIBUTE_DIRECTORY
  78     FILE_ATTRIBUTE_ENCRYPTED     FILE_ATTRIBUTE_NOT_CONTENT_INDEXED
  79     FILE_ATTRIBUTE_REPARSE_POINT FILE_ATTRIBUTE_SPARSE_FILE
  80         FILE_ATTRIBUTE_ARCHIVE           FILE_ATTRIBUTE_COMPRESSED
  81         FILE_ATTRIBUTE_HIDDEN            FILE_ATTRIBUTE_NORMAL
  82         FILE_ATTRIBUTE_OFFLINE           FILE_ATTRIBUTE_READONLY
  83         FILE_ATTRIBUTE_SYSTEM            FILE_ATTRIBUTE_TEMPORARY )],
  84     FILE_FLAG_ =>       [qw(
  85         FILE_FLAG_BACKUP_SEMANTICS      FILE_FLAG_DELETE_ON_CLOSE
  86         FILE_FLAG_NO_BUFFERING          FILE_FLAG_OVERLAPPED
  87         FILE_FLAG_POSIX_SEMANTICS       FILE_FLAG_RANDOM_ACCESS
  88         FILE_FLAG_SEQUENTIAL_SCAN       FILE_FLAG_WRITE_THROUGH
  89         FILE_FLAG_OPEN_REPARSE_POINT )],
  90     FILE_SHARE_ =>      [qw(
  91         FILE_SHARE_DELETE       FILE_SHARE_READ         FILE_SHARE_WRITE )],
  92     FILE_TYPE_ =>       [qw(
  93         FILE_TYPE_CHAR          FILE_TYPE_DISK          FILE_TYPE_PIPE
  94         FILE_TYPE_UNKNOWN )],
  95     FS_ =>      [qw(
  96         FS_CASE_IS_PRESERVED            FS_CASE_SENSITIVE
  97         FS_UNICODE_STORED_ON_DISK       FS_PERSISTENT_ACLS
  98         FS_FILE_COMPRESSION             FS_VOL_IS_COMPRESSED )],
  99         FSCTL_ => [qw(
 100         FSCTL_SET_REPARSE_POINT         FSCTL_GET_REPARSE_POINT
 101         FSCTL_DELETE_REPARSE_POINT )],
 102     HANDLE_FLAG_ =>     [qw(
 103         HANDLE_FLAG_INHERIT             HANDLE_FLAG_PROTECT_FROM_CLOSE )],
 104     IOCTL_STORAGE_ =>   [qw(
 105         IOCTL_STORAGE_CHECK_VERIFY      IOCTL_STORAGE_MEDIA_REMOVAL
 106         IOCTL_STORAGE_EJECT_MEDIA       IOCTL_STORAGE_LOAD_MEDIA
 107         IOCTL_STORAGE_RESERVE           IOCTL_STORAGE_RELEASE
 108         IOCTL_STORAGE_FIND_NEW_DEVICES  IOCTL_STORAGE_GET_MEDIA_TYPES
 109         )],
 110     IOCTL_DISK_ =>      [qw(
 111         IOCTL_DISK_FORMAT_TRACKS        IOCTL_DISK_FORMAT_TRACKS_EX
 112         IOCTL_DISK_GET_DRIVE_GEOMETRY   IOCTL_DISK_GET_DRIVE_LAYOUT
 113         IOCTL_DISK_GET_MEDIA_TYPES      IOCTL_DISK_GET_PARTITION_INFO
 114         IOCTL_DISK_HISTOGRAM_DATA       IOCTL_DISK_HISTOGRAM_RESET
 115         IOCTL_DISK_HISTOGRAM_STRUCTURE  IOCTL_DISK_IS_WRITABLE
 116         IOCTL_DISK_LOGGING              IOCTL_DISK_PERFORMANCE
 117         IOCTL_DISK_REASSIGN_BLOCKS      IOCTL_DISK_REQUEST_DATA
 118         IOCTL_DISK_REQUEST_STRUCTURE    IOCTL_DISK_SET_DRIVE_LAYOUT
 119         IOCTL_DISK_SET_PARTITION_INFO   IOCTL_DISK_VERIFY )],
 120     GENERIC_ =>         [qw(
 121         GENERIC_ALL                     GENERIC_EXECUTE
 122         GENERIC_READ                    GENERIC_WRITE )],
 123     MEDIA_TYPE =>       [qw(
 124         Unknown                 F5_1Pt2_512             F3_1Pt44_512
 125         F3_2Pt88_512            F3_20Pt8_512            F3_720_512
 126         F5_360_512              F5_320_512              F5_320_1024
 127         F5_180_512              F5_160_512              RemovableMedia
 128         FixedMedia              F3_120M_512 )],
 129     MOVEFILE_ =>        [qw(
 130         MOVEFILE_COPY_ALLOWED           MOVEFILE_DELAY_UNTIL_REBOOT
 131         MOVEFILE_REPLACE_EXISTING       MOVEFILE_WRITE_THROUGH )],
 132     SECURITY_ =>        [qw(
 133         SECURITY_ANONYMOUS              SECURITY_CONTEXT_TRACKING
 134         SECURITY_DELEGATION             SECURITY_EFFECTIVE_ONLY
 135         SECURITY_IDENTIFICATION         SECURITY_IMPERSONATION
 136         SECURITY_SQOS_PRESENT )],
 137     SEM_ =>             [qw(
 138         SEM_FAILCRITICALERRORS          SEM_NOGPFAULTERRORBOX
 139         SEM_NOALIGNMENTFAULTEXCEPT      SEM_NOOPENFILEERRORBOX )],
 140     PARTITION_ =>       [qw(
 141         PARTITION_ENTRY_UNUSED          PARTITION_FAT_12
 142         PARTITION_XENIX_1               PARTITION_XENIX_2
 143         PARTITION_FAT_16                PARTITION_EXTENDED
 144         PARTITION_HUGE                  PARTITION_IFS
 145         PARTITION_FAT32                 PARTITION_FAT32_XINT13
 146         PARTITION_XINT13                PARTITION_XINT13_EXTENDED
 147         PARTITION_PREP                  PARTITION_UNIX
 148         VALID_NTFT                      PARTITION_NTFT )],
 149     STD_HANDLE_ =>              [qw(
 150         STD_INPUT_HANDLE                STD_OUTPUT_HANDLE
 151         STD_ERROR_HANDLE )],
 152 );
 153 @EXPORT_OK= ();
 154 {
 155     my $key;
 156     foreach $key (  keys(%EXPORT_TAGS)  ) {
 157         push( @EXPORT_OK, @{$EXPORT_TAGS{$key}} );
 158         #push( @EXPORT_FAIL, @{$EXPORT_TAGS{$key}} )   unless  $key =~ /^Func/;
 159     }
 160 }
 161 $EXPORT_TAGS{ALL}= \@EXPORT_OK;
 162
 163 bootstrap Win32API::File $VERSION;
 164
 165 # Preloaded methods go here.
 166
 167 # To convert C constants to Perl code in cFile.pc
 168 # [instead of C or C++ code in cFile.h]:
 169 #    * Modify F<Makefile.PL> to add WriteMakeFile() =>
 170 #      CONST2PERL/postamble => [[ "Win32API::File" => ]] WRITE_PERL => 1.
 171 #    * Either comment out C<#include "cFile.h"> from F<File.xs>
 172 #      or make F<cFile.h> an empty file.
 173 #    * Make sure the following C<if> block is not commented out.
 174 #    * "nmake clean", "perl Makefile.PL", "nmake"
 175
 176 if(  ! defined &GENERIC_READ  ) {
 177     require "Win32API/File/cFile.pc";
 178 }
 179
 180 sub fileConstant
 181 {
 182     my( $name )= @_;
 183     if(  1 != @_  ||  ! $name  ||  $name =~ /\W/  ) {
 184         require Carp;
 185         Carp::croak( 'Usage: ',__PACKAGE__,'::fileConstant("CONST_NAME")' );
 186     }
 187     my $proto= prototype $name;
 188     if(  defined \&$name
 189      &&  defined $proto
 190      &&  "" eq $proto  ) {
 191         no strict 'refs';
 192         return &$name;
 193     }
 194     return undef;
 195 }
 196
 197 # We provide this for backwards compatibility:
 198 sub constant
 199 {
 200     my( $name )= @_;
 201     my $value= fileConstant( $name );
 202     if(  defined $value  ) {
 203         $!= 0;
 204         return $value;
 205     }
 206     $!= 11; # EINVAL
 207     return 0;
 208 }
 209
 210 # BEGIN {
 211 #     my $code= 'return _fileLastError(@_)';
 212 #     local( $!, $^E )= ( 1, 1 );
 213 #     if(  $! ne $^E  ) {
 214 #       $code= '
 215 #           local( $^E )= _fileLastError(@_);
 216 #           my $ret= $^E;
 217 #           return $ret;
 218 #       ';
 219 #     }
 220 #     eval "sub fileLastError { $code }";
 221 #     die "$@"   if  $@;
 222 # }
 223
 224 package Win32API::File::_error;
 225
 226 use overload
 227     '""' => sub {
 228         require Win32 unless defined &Win32::FormatMessage;
 229         $_ = Win32::FormatMessage(Win32API::File::_fileLastError());
 230         tr/\r\n//d;
 231         return $_;
 232     },
 233     '0+' => sub { Win32API::File::_fileLastError() },
 234     'fallback' => 1;
 235
 236 sub new { return bless {}, shift }
 237 sub set { Win32API::File::_fileLastError($_[1]); return $_[0] }
 238
 239 package Win32API::File;
 240
 241 my $_error = Win32API::File::_error->new();
 242
 243 sub fileLastError {
 244     croak 'Usage: ',__PACKAGE__,'::fileLastError( [$setWin32ErrCode] )' if @_ > 1;
 245     $_error->set($_[0]) if defined $_[0];
 246     return $_error;
 247 }
 248
 249 # Since we ISA DynaLoader which ISA AutoLoader, we ISA AutoLoader so we
 250 # need this next chunk to prevent Win32API::File->nonesuch() from
 251 # looking for "nonesuch.al" and producing confusing error messages:
 252 use vars qw($AUTOLOAD);
 253 sub AUTOLOAD {
 254     require Carp;
 255     Carp::croak(
 256       "Can't locate method $AUTOLOAD via package Win32API::File" );
 257 }
 258
 259 # Replace "&rout;" with "goto &rout;" when that is supported on Win32.
 260
 261 # Aliases for non-Unicode functions:
 262 sub CopyFile                    { &CopyFileA; }
 263 sub CreateFile                  { &CreateFileA; }
 264 sub DefineDosDevice             { &DefineDosDeviceA; }
 265 sub DeleteFile                  { &DeleteFileA; }
 266 sub GetDriveType                { &GetDriveTypeA; }
 267 sub GetFileAttributes   { &GetFileAttributesA; }
 268 sub GetLogicalDriveStrings      { &GetLogicalDriveStringsA; }
 269 sub GetVolumeInformation        { &GetVolumeInformationA; }
 270 sub MoveFile                    { &MoveFileA; }
 271 sub MoveFileEx                  { &MoveFileExA; }
 272 sub QueryDosDevice              { &QueryDosDeviceA; }
 273
 274 sub OsFHandleOpen {
 275     if(  3 != @_  ) {
 276         croak 'Win32API::File Usage:  ',
 277               'OsFHandleOpen(FILE,$hNativeHandle,"rwatb")';
 278     }
 279     my( $fh, $osfh, $access )= @_;
 280     if(  ! ref($fh)  ) {
 281         if(  $fh !~ /('|::)/  ) {
 282             $fh= caller() . "::" . $fh;
 283         }
 284         no strict "refs";
 285         $fh= \*{$fh};
 286     }
 287     my( $mode, $pref );
 288     if(  $access =~ /r/i  ) {
 289         if(  $access =~ /w/i  ) {
 290             $mode= O_RDWR;
 291             $pref= "+<";
 292         } else {
 293             $mode= O_RDONLY;
 294             $pref= "<";
 295         }
 296     } else {
 297         if(  $access =~ /w/i  ) {
 298             $mode= O_WRONLY;
 299             $pref= ">";
 300         } else {
 301         #   croak qq<Win32API::File::OsFHandleOpen():  >,
 302         #         qq<Access ($access) missing both "r" and "w">;
 303             $mode= O_RDONLY;
 304             $pref= "<";
 305         }
 306     }
 307     $mode |= O_APPEND   if  $access =~ /a/i;
 308     #$mode |= O_TEXT   if  $access =~ /t/i;
 309     # Some versions of the Fcntl module are broken and won't autoload O_TEXT:
 310     if(  $access =~ /t/i  ) {
 311         my $o_text= eval "O_TEXT";
 312         $o_text= 0x4000   if  $@;
 313         $mode |= $o_text;
 314     }
 315     $mode |= O_BINARY   if  $access =~ /b/i;
 316     my $fd = eval { OsFHandleOpenFd( $osfh, $mode ) };
 317     if ($@) {
 318         return tie *{$fh}, __PACKAGE__, $osfh;
 319     }
 320     return  undef if  $fd < 0;
 321     return  open( $fh, $pref."&=".$fd );
 322 }
 323
 324 sub GetOsFHandle {
 325     if(  1 != @_  ) {
 326         croak 'Win32API::File Usage:  $OsFHandle= GetOsFHandle(FILE)';
 327     }
 328     my( $file )= @_;
 329     if(  ! ref($file)  ) {
 330         if(  $file !~ /('|::)/  ) {
 331             $file= caller() . "::" . $file;
 332         }
 333         no strict "refs";
 334         # The eval "" is necessary in Perl 5.6, avoid it otherwise.
 335         my $tied = !defined($^]) || $^] < 5.008
 336                        ? eval "tied *{$file}"
 337                        : tied *{$file};
 338
 339         if (UNIVERSAL::isa($tied => __PACKAGE__)) {
 340                 return $tied->win32_handle;
 341         }
 342
 343         $file= *{$file};
 344     }
 345     my( $fd )= fileno($file);
 346     if(  ! defined( $fd )  ) {
 347         if(  $file =~ /^\d+\Z/  ) {
 348             $fd= $file;
 349         } else {
 350             return ();  # $! should be set by fileno().
 351         }
 352     }
 353     my $h= FdGetOsFHandle( $fd );
 354     if(  INVALID_HANDLE_VALUE() == $h  ) {
 355         $h= "";
 356     } elsif(  "0" eq $h  ) {
 357         $h= "0 but true";
 358     }
 359     return $h;
 360 }
 361
 362 sub getFileSize {
 363     croak 'Win32API::File Usage:  $size= getFileSize($hNativeHandle)'
 364         if @_ != 1;
 365
 366     my $handle    = shift;
 367     my $high_size = 0;
 368
 369     my $low_size = GetFileSize($handle, $high_size);
 370
 371     my $retval = $_64BITINT ? $high_size : Math::BigInt->new($high_size);
 372
 373     $retval <<= $THIRTY_TWO;
 374     $retval +=  $low_size;
 375
 376     return $retval;
 377 }
 378
 379 sub setFilePointer {
 380     croak 'Win32API::File Usage:  $pos= setFilePointer($hNativeHandle, $posl, $from_where)'
 381         if @_ != 3;
 382
 383     my ($handle, $pos, $from_where) = @_;
 384
 385     my ($pos_low, $pos_high) = ($pos, 0);
 386
 387     if ($_64BITINT) {
 388         $pos_low  = ($pos & $FFFFFFFF);
 389         $pos_high = (($pos >> $THIRTY_TWO) & $FFFFFFFF);
 390     }
 391     elsif (UNIVERSAL::isa($pos => 'Math::BigInt')) {
 392         $pos_low  = ($pos & $FFFFFFFF)->numify();
 393         $pos_high = (($pos >> $THIRTY_TWO) & $FFFFFFFF)->numify();
 394     }
 395
 396     my $retval = SetFilePointer($handle, $pos_low, $pos_high, $from_where);
 397
 398     if (defined $pos_high && $pos_high != 0) {
 399         if (! $_64BITINT) {
 400             $retval   = Math::BigInt->new($retval);
 401             $pos_high = Math::BigInt->new($pos_high);
 402         }
 403
 404         $retval += $pos_high << $THIRTY_TWO;
 405     }
 406
 407     return $retval;
 408 }
 409
 410 sub attrLetsToBits
 411 {
 412     my( $lets )= @_;
 413     my( %a )= (
 414       "a"=>FILE_ATTRIBUTE_ARCHIVE(),    "c"=>FILE_ATTRIBUTE_COMPRESSED(),
 415       "h"=>FILE_ATTRIBUTE_HIDDEN(),     "o"=>FILE_ATTRIBUTE_OFFLINE(),
 416       "r"=>FILE_ATTRIBUTE_READONLY(),   "s"=>FILE_ATTRIBUTE_SYSTEM(),
 417       "t"=>FILE_ATTRIBUTE_TEMPORARY() );
 418     my( $bits )= 0;
 419     foreach(  split(//,$lets)  ) {
 420         croak "Win32API::File::attrLetsToBits: Unknown attribute letter ($_)"
 421           unless  exists $a{$_};
 422         $bits |= $a{$_};
 423     }
 424     return $bits;
 425 }
 426
 427 use vars qw( @_createFile_Opts %_createFile_Opts );
 428 @_createFile_Opts= qw( Access Create Share Attributes
 429                        Flags Security Model );
 430 @_createFile_Opts{@_createFile_Opts}= (1) x @_createFile_Opts;
 431
 432 sub createFile
 433 {
 434     my $opts= "";
 435     if(  2 <= @_  &&  "HASH" eq ref($_[$#_])  ) {
 436         $opts= pop( @_ );
 437     }
 438     my( $sPath, $svAccess, $svShare )= @_;
 439     if(  @_ < 1  ||  3 < @_  ) {
 440         croak "Win32API::File::createFile() usage:  \$hObject= createFile(\n",
 441               "  \$sPath, [\$svAccess_qrw_ktn_ce,[\$svShare_rwd,]]",
 442               " [{Option=>\$Value}] )\n",
 443               "    options: @_createFile_Opts\nCalled";
 444     }
 445     my( $create, $flags, $sec, $model )= ( "", 0, [], 0 );
 446     if(  ref($opts)  ) {
 447         my @err= grep( ! $_createFile_Opts{$_}, keys(%$opts) );
 448         @err  and  croak "_createFile:  Invalid options (@err)";
 449         $flags= $opts->{Flags}          if  exists( $opts->{Flags} );
 450         $flags |= attrLetsToBits( $opts->{Attributes} )
 451                                         if  exists( $opts->{Attributes} );
 452         $sec= $opts->{Security}         if  exists( $opts->{Security} );
 453         $model= $opts->{Model}          if  exists( $opts->{Model} );
 454         $svAccess= $opts->{Access}      if  exists( $opts->{Access} );
 455         $create= $opts->{Create}        if  exists( $opts->{Create} );
 456         $svShare= $opts->{Share}        if  exists( $opts->{Share} );
 457     }
 458     $svAccess= "r"              unless  defined($svAccess);
 459     $svShare= "rw"              unless  defined($svShare);
 460     if(  $svAccess =~ /^[qrw ktn ce]*$/i  ) {
 461         ( my $c= $svAccess ) =~ tr/qrw QRW//d;
 462         $create= $c   if  "" ne $c  &&  "" eq $create;
 463         local( $_ )= $svAccess;
 464         $svAccess= 0;
 465         $svAccess |= GENERIC_READ()   if  /r/i;
 466         $svAccess |= GENERIC_WRITE()   if  /w/i;
 467     } elsif(  "?" eq $svAccess  ) {
 468         croak
 469           "Win32API::File::createFile:  \$svAccess can use the following:\n",
 470               "    One or more of the following:\n",
 471               "\tq -- Query access (same as 0)\n",
 472               "\tr -- Read access (GENERIC_READ)\n",
 473               "\tw -- Write access (GENERIC_WRITE)\n",
 474               "    At most one of the following:\n",
 475               "\tk -- Keep if exists\n",
 476               "\tt -- Truncate if exists\n",
 477               "\tn -- New file only (fail if file already exists)\n",
 478               "    At most one of the following:\n",
 479               "\tc -- Create if doesn't exist\n",
 480               "\te -- Existing file only (fail if doesn't exist)\n",
 481               "  ''   is the same as 'q  k e'\n",
 482               "  'r'  is the same as 'r  k e'\n",
 483               "  'w'  is the same as 'w  t c'\n",
 484               "  'rw' is the same as 'rw k c'\n",
 485               "  'rt' or 'rn' implies 'c'.\n",
 486               "  Or \$svAccess can be numeric.\n", "Called from";
 487     } elsif(  $svAccess == 0  &&  $svAccess !~ /^[-+.]*0/  ) {
 488         croak "Win32API::File::createFile:  Invalid \$svAccess ($svAccess)";
 489     }
 490     if(  $create =~ /^[ktn ce]*$/  ) {
 491         local( $_ )= $create;
 492         my( $k, $t, $n, $c, $e )= ( scalar(/k/i), scalar(/t/i),
 493           scalar(/n/i), scalar(/c/i), scalar(/e/i) );
 494         if(  1 < $k + $t + $n  ) {
 495             croak "Win32API::File::createFile: \$create must not use ",
 496               qq<more than one of "k", "t", and "n" ($create)>;
 497         }
 498         if(  $c  &&  $e  ) {
 499             croak "Win32API::File::createFile: \$create must not use ",
 500               qq<both "c" and "e" ($create)>;
 501         }
 502         my $r= ( $svAccess & GENERIC_READ() ) == GENERIC_READ();
 503         my $w= ( $svAccess & GENERIC_WRITE() ) == GENERIC_WRITE();
 504         if(  ! $k  &&  ! $t  &&  ! $n  ) {
 505             if(  $w  &&  ! $r  ) {              $t= 1;
 506             } else {                            $k= 1; }
 507         }
 508         if(  $k  ) {
 509             if(  $c  ||  $w && ! $e  ) {        $create= OPEN_ALWAYS();
 510             } else {                            $create= OPEN_EXISTING(); }
 511         } elsif(  $t  ) {
 512             if(  $e  ) {                        $create= TRUNCATE_EXISTING();
 513             } else {                            $create= CREATE_ALWAYS(); }
 514         } else { # $n
 515             if(  ! $e  ) {                      $create= CREATE_NEW();
 516             } else {
 517                 croak "Win32API::File::createFile: \$create must not use ",
 518                   qq<both "n" and "e" ($create)>;
 519             }
 520         }
 521     } elsif(  "?" eq $create  ) {
 522         croak 'Win32API::File::createFile: $create !~ /^[ktn ce]*$/;',
 523               ' pass $svAccess as "?" for more information.';
 524     } elsif(  $create == 0  &&  $create ne "0"  ) {
 525         croak "Win32API::File::createFile: Invalid \$create ($create)";
 526     }
 527     if(  $svShare =~ /^[drw]*$/  ) {
 528         my %s= ( "d"=>FILE_SHARE_DELETE(), "r"=>FILE_SHARE_READ(),
 529                  "w"=>FILE_SHARE_WRITE() );
 530         my @s= split(//,$svShare);
 531         $svShare= 0;
 532         foreach( @s ) {
 533             $svShare |= $s{$_};
 534         }
 535     } elsif(  $svShare == 0  &&  $svShare !~ /^[-+.]*0/  ) {
 536         croak "Win32API::File::createFile: Invalid \$svShare ($svShare)";
 537     }
 538     return  CreateFileA(
 539               $sPath, $svAccess, $svShare, $sec, $create, $flags, $model );
 540 }
 541
 542
 543 sub getLogicalDrives
 544 {
 545     my( $ref )= @_;
 546     my $s= "";
 547     if(  ! GetLogicalDriveStringsA( 256, $s )  ) {
 548         return undef;
 549     }
 550     if(  ! defined($ref)  ) {
 551         return  split( /\0/, $s );
 552     } elsif(  "ARRAY" ne ref($ref)  ) {
 553         croak 'Usage:  C<@arr= getLogicalDrives()> ',
 554               'or C<getLogicalDrives(\\@arr)>', "\n";
 555     }
 556     @$ref= split( /\0/, $s );
 557     return $ref;
 558 }
 559
 560 ###############################################################################
 561 #   Experimental Tied Handle and Object Oriented interface.                   #
 562 ###############################################################################
 563
 564 sub new {
 565         my $class = shift;
 566         $class = ref $class || $class;
 567
 568         my $self = IO::File::new($class);
 569         tie *$self, __PACKAGE__;
 570
 571         $self->open(@_) if @_;
 572
 573         return $self;
 574 }
 575
 576 sub TIEHANDLE {
 577         my ($class, $win32_handle) = @_;
 578         $class = ref $class || $class;
 579
 580         return bless {
 581                 _win32_handle => $win32_handle,
 582                 _binmode      => 0,
 583                 _buffered     => 0,
 584                 _buffer       => '',
 585                 _eof          => 0,
 586                 _fileno       => undef,
 587                 _access       => 'r',
 588                 _append       => 0,
 589         }, $class;
 590 }
 591
 592 # This is called for getting the tied object from hard refs to glob refs in
 593 # some cases, for reasons I don't quite grok.
 594
 595 sub FETCH { return $_[0] }
 596
 597 # Public accessors
 598
 599 sub win32_handle{ $_[0]->{_win32_handle}||= $_[1] }
 600
 601 # Protected accessors
 602
 603 sub _buffer     { $_[0]->{_buffer}      ||= $_[1] }
 604 sub _binmode    { $_[0]->{_binmode}     ||= $_[1] }
 605 sub _fileno     { $_[0]->{_fileno}      ||= $_[1] }
 606 sub _access     { $_[0]->{_access}      ||= $_[1] }
 607 sub _append     { $_[0]->{_append}      ||= $_[1] }
 608
 609 # Tie interface
 610
 611 sub OPEN {
 612         my $self  = shift;
 613         my $expr  = shift;
 614         croak "Only the two argument form of open is supported at this time" if @_;
 615 # FIXME: this needs to parse the full Perl open syntax in $expr
 616
 617         my ($mixed, $mode, $path) =
 618                 ($expr =~ /^\s* (\+)? \s* (<|>|>>)? \s* (.*?) \s*$/x);
 619
 620         croak "Unsupported open mode" if not $path;
 621
 622         my $access = 'r';
 623         my $append = $mode eq '>>' ? 1 : 0;
 624
 625         if ($mixed) {
 626                 $access = 'rw';
 627         } elsif($mode eq '>') {
 628                 $access = 'w';
 629         }
 630
 631         my $w32_handle = createFile($path, $access);
 632
 633         $self->win32_handle($w32_handle);
 634
 635         $self->seek(1,2) if $append;
 636
 637         $self->_access($access);
 638         $self->_append($append);
 639
 640         return 1;
 641 }
 642
 643 sub BINMODE {
 644         $_[0]->_binmode(1);
 645 }
 646
 647 sub WRITE {
 648         my ($self, $buf, $len, $offset, $overlap) = @_;
 649
 650         if ($offset) {
 651                 $buf = substr($buf, $offset);
 652                 $len = length($buf);
 653         }
 654
 655         $len       = length($buf) if not defined $len;
 656
 657         $overlap   = [] if not defined $overlap;;
 658
 659         my $bytes_written = 0;
 660
 661         WriteFile (
 662                 $self->win32_handle, $buf, $len,
 663                 $bytes_written, $overlap
 664         );
 665
 666         return $bytes_written;
 667 }
 668
 669 sub PRINT {
 670         my $self = shift;
 671
 672         my $buf = join defined $, ? $, : "" => @_;
 673
 674         $buf =~ s/\012/\015\012/sg unless $self->_binmode();
 675
 676         $buf .= $\ if defined $\;
 677
 678         $self->WRITE($buf, length($buf), 0);
 679 }
 680
 681 sub READ {
 682         my $self = shift;
 683         my $into = \$_[0]; shift;
 684         my ($len, $offset, $overlap) = @_;
 685
 686         my $buffer     = defined $self->_buffer ? $self->_buffer : "";
 687         my $buf_length = length($buffer);
 688         my $bytes_read = 0;
 689         my $data;
 690         $offset        = 0 if not defined $offset;
 691
 692         if ($buf_length >= $len) {
 693                 $data       = substr($buffer, 0, $len => "");
 694                 $bytes_read = $len;
 695                 $self->_buffer($buffer);
 696         } else {
 697                 if ($buf_length > 0) {
 698                         $len -= $buf_length;
 699                         substr($$into, $offset) = $buffer;
 700                         $offset += $buf_length;
 701                 }
 702
 703                 $overlap ||= [];
 704
 705                 ReadFile (
 706                         $self->win32_handle, $data, $len,
 707                         $bytes_read, $overlap
 708                 );
 709         }
 710
 711         $$into = "" if not defined $$into;
 712
 713         substr($$into, $offset) = $data;
 714
 715         return $bytes_read;
 716 }
 717
 718 sub READLINE {
 719         my $self = shift;
 720         my $line = "";
 721
 722         while ((index $line, $/) == -1) { # read until end of line marker
 723                 my $char = $self->GETC();
 724
 725                 last if !defined $char || $char eq '';
 726
 727                 $line .= $char;
 728         }
 729
 730         return undef if $line eq '';
 731
 732         return $line;
 733 }
 734
 735
 736 sub FILENO {
 737         my $self = shift;
 738
 739         return $self->_fileno() if defined $self->_fileno();
 740
 741         return -1 if $^O eq 'cygwin';
 742
 743 # FIXME: We don't always open the handle, better to query the handle or to set
 744 # the right access info at TIEHANDLE time.
 745
 746         my $access = $self->_access();
 747         my $mode   = $access eq 'rw' ? O_RDWR :
 748                 $access eq 'w' ? O_WRONLY : O_RDONLY;
 749
 750         $mode |= O_APPEND if $self->_append();
 751
 752         $mode |= O_TEXT   if not $self->_binmode();
 753
 754         return $self->_fileno ( OsfHandleOpenFd (
 755                 $self->win32_handle, $mode
 756         ));
 757 }
 758
 759 sub SEEK {
 760         my ($self, $pos, $whence) = @_;
 761
 762         $whence = 0 if not defined $whence;
 763         my @file_consts = map {
 764                 fileConstant($_)
 765         } qw(FILE_BEGIN FILE_CURRENT FILE_END);
 766
 767         my $from_where = $file_consts[$whence];
 768
 769         return setFilePointer($self->win32_handle, $pos, $from_where);
 770 }
 771
 772 sub TELL {
 773 # SetFilePointer with position 0 at FILE_CURRENT will return position.
 774         return $_[0]->SEEK(0, 1);
 775 }
 776
 777 sub EOF {
 778         my $self = shift;
 779
 780         my $current = $self->TELL() + 0;
 781         my $end     = getFileSize($self->win32_handle) + 0;
 782
 783         return $current == $end;
 784 }
 785
 786 sub CLOSE {
 787         my $self = shift;
 788
 789         my $retval = 1;
 790
 791         if (defined $self->win32_handle) {
 792                 $retval = CloseHandle($self->win32_handle);
 793
 794                 $self->win32_handle(undef);
 795         }
 796
 797         return $retval;
 798 }
 799
 800 # Only close the handle on explicit close, too many problems otherwise.
 801 sub UNTIE {}
 802
 803 sub DESTROY {}
 804
 805 # End of Tie/OO Interface
 806
 807 # Autoload methods go after =cut, and are processed by the autosplit program.
 808
 809 1;
 810 __END__
 811
 812 =head1 NAME
 813
 814 Win32API::File - Low-level access to Win32 system API calls for files/dirs.
 815
 816 =head1 SYNOPSIS
 817
 818   use Win32API::File 0.08 qw( :ALL );
 819
 820   MoveFile( $Source, $Destination )
 821     or  die "Can't move $Source to $Destination: ",fileLastError(),"\n";
 822   MoveFileEx( $Source, $Destination, MOVEFILE_REPLACE_EXISTING() )
 823     or  die "Can't move $Source to $Destination: ",fileLastError(),"\n";
 824   [...]
 825
 826 =head1 DESCRIPTION
 827
 828 This provides fairly low-level access to the Win32 System API
 829 calls dealing with files and directories.
 830
 831 To pass in C<NULL> as the pointer to an optional buffer, pass in
 832 an empty list reference, C<[]>.
 833
 834 Beyond raw access to the API calls and related constants, this module
 835 handles smart buffer allocation and translation of return codes.
 836
 837 All functions, unless otherwise noted, return a true value for success
 838 and a false value for failure and set C<$^E> on failure.
 839
 840 =head2 Object Oriented/Tied Handle Interface
 841
 842 WARNING: this is new code, use at your own risk.
 843
 844 This version of C<Win32API::File> can be used like an C<IO::File> object:
 845
 846   my $file = Win32API::File->new("+> foo");
 847   binmode $file;
 848   print $file "hello there\n";
 849   seek $file, 0, 0;
 850   my $line = <$file>;
 851   $file->close;
 852
 853 It also supports tying via a win32 handle (for example, from C<createFile()>):
 854
 855   tie FILE, 'Win32API::File', $win32_handle;
 856   print FILE "...";
 857
 858 It has not been extensively tested yet and buffered I/O is not yet implemented.
 859
 860 =head2 Exports
 861
 862 Nothing is exported by default.  The following tags can be used to
 863 have large sets of symbols exported:  C<":Func">, C<":FuncA">,
 864 C<":FuncW">, C<":Misc">, C<":DDD_">, C<":DRIVE_">, C<":FILE_">,
 865 C<":FILE_ATTRIBUTE_">, C<":FILE_FLAG_">, C<":FILE_SHARE_">,
 866 C<":FILE_TYPE_">, C<":FS_">, C<":FSCTL_">, C<":HANDLE_FLAG_">,
 867 C<":IOCTL_STORAGE_">, C<":IOCTL_DISK_">, C<":GENERIC_">,
 868 C<":MEDIA_TYPE">, C<":MOVEFILE_">, C<":SECURITY_">, C<":SEM_">,
 869 and C<":PARTITION_">.
 870
 871 =over
 872
 873 =item C<":Func">
 874
 875 The basic function names:  C<attrLetsToBits>,         C<createFile>,
 876 C<fileConstant>,           C<fileLastError>,          C<getLogicalDrives>,
 877 C<setFilePointer>,         C<getFileSize>,
 878 C<CloseHandle>,            C<CopyFile>,               C<CreateFile>,
 879 C<DefineDosDevice>,        C<DeleteFile>,             C<DeviceIoControl>,
 880 C<FdGetOsFHandle>,         C<GetDriveType>,           C<GetFileAttributes>,
 881 C<GetFileSize>,            C<GetFileType>,            C<GetHandleInformation>,
 882 C<GetLogicalDrives>,       C<GetLogicalDriveStrings>, C<GetOsFHandle>,
 883 C<GetOverlappedResult>,    C<GetVolumeInformation>,   C<IsContainerPartition>,
 884 C<IsRecognizedPartition>,  C<MoveFile>,               C<MoveFileEx>,
 885 C<OsFHandleOpen>,          C<OsFHandleOpenFd>,        C<QueryDosDevice>,
 886 C<ReadFile>,               C<SetErrorMode>,           C<SetFilePointer>,
 887 C<SetHandleInformation>,   and C<WriteFile>.
 888
 889 =over
 890
 891 =item attrLetsToBits
 892
 893 =item C<$uBits= attrLetsToBits( $sAttributeLetters )>
 894
 895 Converts a string of file attribute letters into an unsigned value with
 896 the corresponding bits set.  C<$sAttributeLetters> should contain zero
 897 or more letters from C<"achorst">:
 898
 899 =over
 900
 901 =item C<"a">
 902
 903 C<FILE_ATTRIBUTE_ARCHIVE>
 904
 905 =item C<"c">
 906
 907 C<FILE_ATTRIBUTE_COMPRESSED>
 908
 909 =item C<"h">
 910
 911 C<FILE_ATTRIBUTE_HIDDEN>
 912
 913 =item C<"o">
 914
 915 C<FILE_ATTRIBUTE_OFFLINE>
 916
 917 =item C<"r">
 918
 919 C<FILE_ATTRIBUTE_READONLY>
 920
 921 =item C<"s">
 922
 923 C<FILE_ATTRIBUTE_SYSTEM>
 924
 925 =item C<"t">
 926
 927 C<FILE_ATTRIBUTE_TEMPORARY>
 928
 929 =back
 930
 931 =item createFile
 932
 933 =item C<$hObject= createFile( $sPath )>
 934
 935 =item C<$hObject= createFile( $sPath, $rvhvOptions )>
 936
 937 =item C<$hObject= createFile( $sPath, $svAccess )>
 938
 939 =item C<$hObject= createFile( $sPath, $svAccess, $rvhvOptions )>
 940
 941 =item C<$hObject= createFile( $sPath, $svAccess, $svShare )>
 942
 943 =item C<$hObject= createFile( $sPath, $svAccess, $svShare, $rvhvOptions )>
 944
 945 This is a Perl-friendly wrapper around C<CreateFile>.
 946
 947 On failure, C<$hObject> gets set to a false value and C<regLastError()>
 948 and C<$^E> are set to the reason for the failure.  Otherwise,
 949 C<$hObject> gets set to a Win32 native file handle which is alwasy
 950 a true value [returns C<"0 but true"> in the impossible(?) case of
 951 the handle having a value of C<0>].
 952
 953 C<$sPath> is the path to the file [or device, etc.] to be opened.  See
 954 C<CreateFile> for more information on possible special values for
 955 C<$sPath>.
 956
 957 C<$svAccess> can be a number containing the bit mask representing
 958 the specific type(s) of access to the file that you desire.  See the
 959 C<$uAccess> parameter to C<CreateFile> for more information on these
 960 values.
 961
 962 More likely, C<$svAccess> is a string describing the generic type of
 963 access you desire and possibly the file creation options to use.  In
 964 this case, C<$svAccess> should contain zero or more characters from
 965 C<"qrw"> [access desired], zero or one character each from C<"ktn">
 966 and C<"ce">, and optional white space.  These letters stand for,
 967 respectively, "Query access", "Read access", "Write access", "Keep if
 968 exists", "Truncate if exists", "New file only", "Create if none", and
 969 "Existing file only".  Case is ignored.
 970
 971 You can pass in C<"?"> for C<$svAccess> to have an error message
 972 displayed summarizing its possible values.  This is very handy when
 973 doing on-the-fly programming using the Perl debugger:
 974
 975     Win32API::File::createFile:  $svAccess can use the following:
 976         One or more of the following:
 977             q -- Query access (same as 0)
 978             r -- Read access (GENERIC_READ)
 979             w -- Write access (GENERIC_WRITE)
 980         At most one of the following:
 981             k -- Keep if exists
 982             t -- Truncate if exists
 983             n -- New file only (fail if file already exists)
 984         At most one of the following:
 985             c -- Create if doesn't exist
 986             e -- Existing file only (fail if doesn't exist)
 987       ''   is the same as 'q  k e'
 988       'r'  is the same as 'r  k e'
 989       'w'  is the same as 'w  t c'
 990       'rw' is the same as 'rw k c'
 991       'rt' or 'rn' implies 'c'.
 992       Or $access can be numeric.
 993
 994 C<$svAccess> is designed to be "do what I mean", so you can skip
 995 the rest of its explanation unless you are interested in the complex
 996 details.  Note that, if you want write access to a device, you need
 997 to specify C<"k"> [and perhaps C<"e">, as in C<"w ke"> or C<"rw ke">]
 998 since Win32 suggests C<OPEN_EXISTING> be used when opening a device.
 999
1000 =over
1001
1002 =item C<"q">
1003
1004 Stands for "Query access".  This is really a no-op since you always have
1005 query access when you open a file.  You can specify C<"q"> to document
1006 that you plan to query the file [or device, etc.].  This is especially
1007 helpful when you don't want read nor write access since something like
1008 C<"q"> or C<"q ke"> may be easier to understand than just C<""> or C<"ke">.
1009
1010 =item C<"r">
1011
1012 Stands for "Read access".  Sets the C<GENERIC_READ> bit(s) in the
1013 C<$uAccess> that is passed to C<CreateFile>.  This is the default
1014 access if the C<$svAccess> parameter is missing [or if it is C<undef>
1015 and C<$rvhvOptions> doesn't specify an C<"Access"> option].
1016
1017 =item C<"w">
1018
1019 Stands for "Write access".  Sets the C<GENERIC_WRITE> bit(s) in the
1020 C<$uAccess> that is passed to C<CreateFile>.
1021
1022 =item C<"k">
1023
1024 Stands for "Keep if exists".  If the requested file exists, then it is
1025 opened.  This is the default unless C<GENERIC_WRITE> access has been
1026 requested but C<GENERIC_READ> access has not been requested.   Contrast
1027 with C<"t"> and C<"n">.
1028
1029 =item C<"t">
1030
1031 Stands for "Truncate if exists".  If the requested file exists, then
1032 it is truncated to zero length and then opened.  This is the default if
1033 C<GENERIC_WRITE> access has been requested and C<GENERIC_READ> access
1034 has not been requested.  Contrast with C<"k"> and C<"n">.
1035
1036 =item C<"n">
1037
1038 Stands for "New file only".  If the requested file exists, then it is
1039 not opened and the C<createFile> call fails.  Contrast with C<"k"> and
1040 C<"t">.  Can't be used with C<"e">.
1041
1042 =item C<"c">
1043
1044 Stands for "Create if none".  If the requested file does not
1045 exist, then it is created and then opened.  This is the default
1046 if C<GENERIC_WRITE> access has been requested or if C<"t"> or
1047 C<"n"> was specified.  Contrast with C<"e">.
1048
1049 =item C<"e">
1050
1051 Stands for "Existing file only".  If the requested file does not
1052 exist, then nothing is opened and the C<createFile> call fails.  This
1053 is the default unless C<GENERIC_WRITE> access has been requested or
1054 C<"t"> or C<"n"> was specified.   Contrast with C<"c">.   Can't be
1055 used with C<"n">.
1056
1057 =back
1058
1059 The characters from C<"ktn"> and C<"ce"> are combined to determine the
1060 what value for C<$uCreate> to pass to C<CreateFile> [unless overridden
1061 by C<$rvhvOptions>]:
1062
1063 =over
1064
1065 =item C<"kc">
1066
1067 C<OPEN_ALWAYS>
1068
1069 =item C<"ke">
1070
1071 C<OPEN_EXISTING>
1072
1073 =item C<"tc">
1074
1075 C<TRUNCATE_EXISTING>
1076
1077 =item C<"te">
1078
1079 C<CREATE_ALWAYS>
1080
1081 =item C<"nc">
1082
1083 C<CREATE_NEW>
1084
1085 =item C<"ne">
1086
1087 Illegal.
1088
1089 =back
1090
1091 C<$svShare> controls how the file is shared, that is, whether other
1092 processes can have read, write, and/or delete access to the file while
1093 we have it opened.  C<$svShare> will usually be a string containing zero
1094 or more characters from C<"rwd"> but can also be a numeric bit mask.
1095
1096 C<"r"> sets the C<FILE_SHARE_READ> bit which allows other processes to have
1097 read access to the file.  C<"w"> sets the C<FILE_SHARE_WRITE> bit which
1098 allows other processes to have write access to the file.  C<"d"> sets the
1099 C<FILE_SHARE_DELETE> bit which allows other processes to have delete access
1100 to the file [ignored under Windows 95].
1101
1102 The default for C<$svShare> is C<"rw"> which provides the same sharing as
1103 using regular perl C<open()>.
1104
1105 If another process currently has read, write, and/or delete access to
1106 the file and you don't allow that level of sharing, then your call to
1107 C<createFile> will fail.  If you requested read, write, and/or delete
1108 access and another process already has the file open but doesn't allow
1109 that level of sharing, then your call to C<createFile> will fail.  Once
1110 you have the file open, if another process tries to open it with read,
1111 write, and/or delete access and you don't allow that level of sharing,
1112 then that process won't be allowed to open the file.
1113
1114 C<$rvhvOptions> is a reference to a hash where any keys must be from
1115 the list C<qw( Access Create Share Attributes Flags Security Model )>.
1116 The meaning of the value depends on the key name, as described below.
1117 Any option values in C<$rvhvOptions> override the settings from
1118 C<$svAccess> and C<$svShare> if they conflict.
1119
1120 =over
1121
1122 =item Flags => $uFlags
1123
1124 C<$uFlags> is an unsigned value having any of the C<FILE_FLAG_*> or
1125 C<FILE_ATTRIBUTE_*> bits set.  Any C<FILE_ATTRIBUTE_*> bits set via the
1126 C<Attributes> option are logically C<or>ed with these bits.  Defaults
1127 to C<0>.
1128
1129 If opening the client side of a named pipe, then you can also specify
1130 C<SECURITY_SQOS_PRESENT> along with one of the other C<SECURITY_*>
1131 constants to specify the security quality of service to be used.
1132
1133 =item Attributes => $sAttributes
1134
1135 A string of zero or more characters from C<"achorst"> [see C<attrLetsToBits>
1136 for more information] which are converted to C<FILE_ATTRIBUTE_*> bits to
1137 be set in the C<$uFlags> argument passed to C<CreateFile>.
1138
1139 =item Security => $pSecurityAttributes
1140
1141 C<$pSecurityAttributes> should contain a C<SECURITY_ATTRIBUTES> structure
1142 packed into a string or C<[]> [the default].
1143
1144 =item Model => $hModelFile
1145
1146 C<$hModelFile> should contain a handle opened with C<GENERIC_READ>
1147 access to a model file from which file attributes and extended attributes
1148 are to be copied.  Or C<$hModelFile> can be C<0> [the default].
1149
1150 =item Access => $sAccess
1151
1152 =item Access => $uAccess
1153
1154 C<$sAccess> should be a string of zero or more characters from
1155 C<"qrw"> specifying the type of access desired:  "query" or C<0>,
1156 "read" or C<GENERIC_READ> [the default], or "write" or
1157 C<GENERIC_WRITE>.
1158
1159 C<$uAccess> should be an unsigned value containing bits set to
1160 indicate the type of access desired.  C<GENERIC_READ> is the default.
1161
1162 =item Create => $sCreate
1163
1164 =item Create => $uCreate
1165
1166 C<$sCreate> should be a string constaing zero or one character from
1167 C<"ktn"> and zero or one character from C<"ce">.  These stand for
1168 "Keep if exists", "Truncate if exists", "New file only", "Create if
1169 none", and "Existing file only".  These are translated into a
1170 C<$uCreate> value.
1171
1172 C<$uCreate> should be one of C<OPEN_ALWAYS>, C<OPEN_EXISTING>,
1173 C<TRUNCATE_EXISTING>, C<CREATE_ALWAYS>, or C<CREATE_NEW>.
1174
1175 =item Share => $sShare
1176
1177 =item Share => $uShare
1178
1179 C<$sShare> should be a string with zero or more characters from
1180 C<"rwd"> that is translated into a C<$uShare> value.  C<"rw"> is
1181 the default.
1182
1183 C<$uShare> should be an unsigned value having zero or more of the
1184 following bits set:  C<FILE_SHARE_READ>, C<FILE_SHARE_WRITE>, and
1185 C<FILE_SHARE_DELETE>.  C<FILE_SHARE_READ|FILE_SHARE_WRITE> is the
1186 default.
1187
1188 =back
1189
1190 Examples:
1191
1192     $hFlop= createFile( "//./A:", "r", "r" )
1193       or  die "Can't prevent others from writing to floppy: $^E\n";
1194     $hDisk= createFile( "//./C:", "rw ke", "" )
1195       or  die "Can't get exclusive access to C: $^E\n";
1196     $hDisk= createFile( $sFilePath, "ke",
1197       { Access=>FILE_READ_ATTRIBUTES } )
1198       or  die "Can't read attributes of $sFilePath: $^E\n";
1199     $hTemp= createFile( "$ENV{Temp}/temp.$$", "wn", "",
1200       { Attributes=>"hst", Flags=>FILE_FLAG_DELETE_ON_CLOSE() } )
1201       or  die "Can't create temporary file, temp.$$: $^E\n";
1202
1203 =item getLogicalDrives
1204
1205 =item C<@roots= getLogicalDrives()>
1206
1207 Returns the paths to the root directories of all logical drives
1208 currently defined.  This includes all types of drive lettters, such
1209 as floppies, CD-ROMs, hard disks, and network shares.  A typical
1210 return value on a poorly equipped computer would be C<("A:\\","C:\\")>.
1211
1212 =item CloseHandle
1213
1214 =item C<CloseHandle( $hObject )>
1215
1216 Closes a Win32 native handle, such as one opened via C<CreateFile>.
1217 Like most routines, returns a true value if successful and a false
1218 value [and sets C<$^E> and C<regLastError()>] on failure.
1219
1220 =item CopyFile
1221
1222 =item C<CopyFile( $sOldFileName, $sNewFileName, $bFailIfExists )>
1223
1224 C<$sOldFileName> is the path to the file to be copied.
1225 C<$sNewFileName> is the path to where the file should be copied.
1226 Note that you can B<NOT> just specify a path to a directory in
1227 C<$sNewFileName> to copy the file to that directory using the
1228 same file name.
1229
1230 If C<$bFailIfExists> is true and C<$sNewFileName> is the path to
1231 a file that already exists, then C<CopyFile> will fail.  If
1232 C<$bFailIfExists> is falsea, then the copy of the C<$sOldFileNmae>
1233 file will overwrite the C<$sNewFileName> file if it already exists.
1234
1235 Like most routines, returns a true value if successful and a false
1236 value [and sets C<$^E> and C<regLastError()>] on failure.
1237
1238 =item CreateFile
1239
1240 =item C<$hObject= CreateFile( $sPath, $uAccess, $uShare, $pSecAttr, $uCreate, $uFlags, $hModel )>
1241
1242 On failure, C<$hObject> gets set to a false value and C<$^E> and
1243 C<fileLastError()> are set to the reason for the failure.  Otherwise,
1244 C<$hObject> gets set to a Win32 native file handle which is always a
1245 true value [returns C<"0 but true"> in the impossible(?) case of the
1246 handle having a value of C<0>].
1247
1248 C<$sPath> is the path to the file [or device, etc.] to be opened.
1249
1250 C<$sPath> can use C<"/"> or C<"\\"> as path delimiters and can even
1251 mix the two.  We will usually only use C<"/"> in our examples since
1252 using C<"\\"> is usually harder to read.
1253
1254 Under Windows NT, C<$sPath> can start with C<"//?/"> to allow the use
1255 of paths longer than C<MAX_PATH> [for UNC paths, replace the leading
1256 C<"//"> with C<"//?/UNC/">, as in C<"//?/UNC/Server/Share/Dir/File.Ext">].
1257
1258 C<$sPath> can start with C<"//./"> to indicate that the rest of the
1259 path is the name of a "DOS device."  You can use C<QueryDosDevice>
1260 to list all current DOS devices and can add or delete them with
1261 C<DefineDosDevice>.  If you get the source-code distribution of this
1262 module from CPAN, then it includes an example script, F<ex/ListDevs.plx>
1263 that will list all current DOS devices and their "native" definition.
1264 Again, note that this doesn't work under Win95 nor Win98.
1265
1266 The most common such DOS devices include:
1267
1268 =over
1269
1270 =item C<"//./PhysicalDrive0">
1271
1272 Your entire first hard disk.  Doesn't work under Windows 95.  This
1273 allows you to read or write raw sectors of your hard disk and to use
1274 C<DeviceIoControl> to perform miscellaneous queries and operations
1275 to the hard disk.   Writing raw sectors and certain other operations
1276 can seriously damage your files or the function of your computer.
1277
1278 Locking this for exclusive access [by specifying C<0> for C<$uShare>]
1279 doesn't prevent access to the partitions on the disk nor their file
1280 systems.  So other processes can still access any raw sectors within
1281 a partition and can use the file system on the disk as usual.
1282
1283 =item C<"//./C:">
1284
1285 Your F<C:> partition.  Doesn't work under Windows 95.  This allows
1286 you to read or write raw sectors of that partition and to use
1287 C<DeviceIoControl> to perform miscellaneous queries and operations
1288 to the partition.  Writing raw sectors and certain other operations
1289 can seriously damage your files or the function of your computer.
1290
1291 Locking this for exclusive access doesn't prevent access to the
1292 physical drive that the partition is on so other processes can
1293 still access the raw sectors that way.  Locking this for exclusive
1294 access B<does> prevent other processes from opening the same raw
1295 partition and B<does> prevent access to the file system on it.  It
1296 even prevents the current process from accessing the file system
1297 on that partition.
1298
1299 =item C<"//./A:">
1300
1301 The raw floppy disk.  Doesn't work under Windows 95.  This allows
1302 you to read or write raw sectors of the floppy disk and to use
1303 C<DeviceIoControl> to perform miscellaneous queries and operations
1304 to the floopy disk or drive.
1305
1306 Locking this for exclusive access prevents all access to the floppy.
1307
1308 =item C<"//./PIPE/PipeName">
1309
1310 A named pipe, created via C<CreateNamedPipe>.
1311
1312 =back
1313
1314 C<$uAccess> is an unsigned value with bits set indicating the
1315 type of access desired.  Usually either C<0> ["query" access],
1316 C<GENERIC_READ>, C<GENERIC_WRITE>, C<GENERIC_READ|GENERIC_WRITE>,
1317 or C<GENERIC_ALL>.  More specific types of access can be specified,
1318 such as C<FILE_APPEND_DATA> or C<FILE_READ_EA>.
1319
1320 C<$uShare> controls how the file is shared, that is, whether other
1321 processes can have read, write, and/or delete access to the file while
1322 we have it opened.  C<$uShare> is an unsigned value with zero or more
1323 of these bits set:  C<FILE_SHARE_READ>, C<FILE_SHARE_WRITE>, and
1324 C<FILE_SHARE_DELETE>.
1325
1326 If another process currently has read, write, and/or delete access to
1327 the file and you don't allow that level of sharing, then your call to
1328 C<CreateFile> will fail.  If you requested read, write, and/or delete
1329 access and another process already has the file open but doesn't allow
1330 that level of sharing, thenn your call to C<createFile> will fail.  Once
1331 you have the file open, if another process tries to open it with read,
1332 write, and/or delete access and you don't allow that level of sharing,
1333 then that process won't be allowed to open the file.
1334
1335 C<$pSecAttr> should either be C<[]> [for C<NULL>] or a
1336 C<SECURITY_ATTRIBUTES> data structure packed into a string.
1337 For example, if C<$pSecDesc> contains a C<SECURITY_DESCRIPTOR>
1338 structure packed into a string, perhaps via:
1339
1340     RegGetKeySecurity( $key, 4, $pSecDesc, 1024 );
1341
1342 then you can set C<$pSecAttr> via:
1343
1344     $pSecAttr= pack( "L P i", 12, $pSecDesc, $bInheritHandle );
1345
1346 C<$uCreate> is one of the following values:  C<OPEN_ALWAYS>,
1347 C<OPEN_EXISTING>, C<TRUNCATE_EXISTING>, C<CREATE_ALWAYS>, and
1348 C<CREATE_NEW>.
1349
1350 C<$uFlags> is an unsigned value with zero or more bits set indicating
1351 attributes to associate with the file [C<FILE_ATTRIBUTE_*> values] or
1352 special options [C<FILE_FLAG_*> values].
1353
1354 If opening the client side of a named pipe, then you can also set
1355 C<$uFlags> to include C<SECURITY_SQOS_PRESENT> along with one of the
1356 other C<SECURITY_*> constants to specify the security quality of
1357 service to be used.
1358
1359 C<$hModel> is C<0> [or C<[]>, both of which mean C<NULL>] or a Win32
1360 native handle opened with C<GENERIC_READ> access to a model file from
1361 which file attributes and extended attributes are to be copied if a
1362 new file gets created.
1363
1364 Examples:
1365
1366     $hFlop= CreateFile( "//./A:", GENERIC_READ(),
1367       FILE_SHARE_READ(), [], OPEN_EXISTING(), 0, [] )
1368       or  die "Can't prevent others from writing to floppy: $^E\n";
1369     $hDisk= CreateFile( $sFilePath, FILE_READ_ATTRIBUTES(),
1370       FILE_SHARE_READ()|FILE_SHARE_WRITE(), [], OPEN_EXISTING(), 0, [] )
1371       or  die "Can't read attributes of $sFilePath: $^E\n";
1372     $hTemp= CreateFile( "$ENV{Temp}/temp.$$", GENERIC_WRITE(), 0,
1373       CREATE_NEW(), FILE_FLAG_DELETE_ON_CLOSE()|attrLetsToBits("hst"), [] )
1374       or  die "Can't create temporary file, temp.$$: $^E\n";
1375
1376 =item DefineDosDevice
1377
1378 =item C<DefineDosDevice( $uFlags, $sDosDeviceName, $sTargetPath )>
1379
1380 Defines a new DOS device, overrides the current definition of a DOS
1381 device, or deletes a definition of a DOS device.  Like most routines,
1382 returns a true value if successful and a false value [and sets C<$^E>
1383 and C<regLastError()>] on failure.
1384
1385 C<$sDosDeviceName> is the name of a DOS device for which we'd like
1386 to add or delete a definition.
1387
1388 C<$uFlags> is an unsigned value with zero or more of the following
1389 bits set:
1390
1391 =over
1392
1393 =item C<DDD_RAW_TARGET_PATH>
1394
1395 Indicates that C<$sTargetPath> will be a raw Windows NT object name.
1396 This usually means that C<$sTargetPath> starts with C<"\\Device\\">.
1397 Note that you cannot use C<"/"> in place of C<"\\"> in raw target path
1398 names.
1399
1400 =item C<DDD_REMOVE_DEFINITION>
1401
1402 Requests that a definition be deleted.  If C<$sTargetPath> is
1403 C<[]> [for C<NULL>], then the most recently added definition for
1404 C<$sDosDeviceName> is removed.  Otherwise the most recently added
1405 definition matching C<$sTargetPath> is removed.
1406
1407 If the last definition is removed, then the DOS device name is
1408 also deleted.
1409
1410 =item C<DDD_EXACT_MATCH_ON_REMOVE>
1411
1412 When deleting a definition, this bit causes each C<$sTargetPath> to
1413 be compared to the full-length definition when searching for the most
1414 recently added match.  If this bit is not set, then C<$sTargetPath>
1415 only needs to match a prefix of the definition.
1416
1417 =back
1418
1419 C<$sTargetPath> is the DOS device's specific definition that you
1420 wish to add or delete.  For C<DDD_RAW_TARGET_PATH>, these usually
1421 start with C<"\\Device\\">.  If the C<DDD_RAW_TARGET_PATH> bit is
1422 not set, then C<$sTargetPath> is just an ordinary path to some file
1423 or directory, providing the functionality of the B<subst> command.
1424
1425 =item DeleteFile
1426
1427 =item C<DeleteFile( $sFileName )>
1428
1429 Deletes the named file.  Compared to Perl's C<unlink>, C<DeleteFile>
1430 has the advantage of not deleting read-only files.  For B<some>
1431 versions of Perl, C<unlink> silently calls C<chmod> whether it needs
1432 to or not before deleting the file so that files that you have
1433 protected by marking them as read-only are not always protected from
1434 Perl's C<unlink>.
1435
1436 Like most routines, returns a true value if successful and a false
1437 value [and sets C<$^E> and C<regLastError()>] on failure.
1438
1439 =item DeviceIoControl
1440
1441 =item C<DeviceIoControl( $hDevice, $uIoControlCode, $pInBuf, $lInBuf, $opOutBuf, $lOutBuf, $olRetBytes, $pOverlapped )>
1442
1443 Requests a special operation on an I/O [input/output] device, such
1444 as ejecting a tape or formatting a disk.  Like most routines, returns
1445 a true value if successful and a false value [and sets C<$^E> and
1446 C<regLastError()>] on failure.
1447
1448 C<$hDevice> is a Win32 native file handle to a device [return value
1449 from C<CreateFile>].
1450
1451 C<$uIoControlCode> is an unsigned value [a C<IOCTL_*> or C<FSCTL_*>
1452 constant] indicating the type query or other operation to be performed.
1453
1454 C<$pInBuf> is C<[]> [for C<NULL>] or a data structure packed into a
1455 string.  The type of data structure depends on the C<$uIoControlCode>
1456 value.  C<$lInBuf> is C<0> or the length of the structure in
1457 C<$pInBuf>.  If C<$pInBuf> is not C<[]> and C<$lInBuf> is C<0>, then
1458 C<$lInBuf> will automatically be set to C<length($pInBuf)> for you.
1459
1460 C<$opOutBuf> is C<[]> [for C<NULL>] or will be set to contain a
1461 returned data structure packed into a string.  C<$lOutBuf> indicates
1462 how much space to allocate in C<$opOutBuf> for C<DeviceIoControl> to
1463 store the data structure.  If C<$lOutBuf> is a number and C<$opOutBuf>
1464 already has a buffer allocated for it that is larger than C<$lOutBuf>
1465 bytes, then this larger buffer size will be passed to C<DeviceIoControl>.
1466 However, you can force a specific buffer size to be passed to
1467 C<DeviceIoControl> by prepending a C<"="> to the front of C<$lOutBuf>.
1468
1469 C<$olRetBytes> is C<[]> or is a scalar to receive the number of bytes
1470 written to C<$opOutBuf>.  Even when C<$olRetBytes> is C<[]>, a valid
1471 pointer to a C<DWORD> [and not C<NULL>] is passed to C<DeviceIoControl>.
1472 In this case, C<[]> just means that you don't care about the value
1473 that might be written to C<$olRetBytes>, which is usually the case
1474 since you can usually use C<length($opOutBuf)> instead.
1475
1476 C<$pOverlapped> is C<[]> or is a C<OVERLAPPED> structure packed into
1477 a string.  This is only useful if C<$hDevice> was opened with the
1478 C<FILE_FLAG_OVERLAPPED> flag set.
1479
1480 =item FdGetOsFHandle
1481
1482 =item C<$hNativeHandle= FdGetOsFHandle( $ivFd )>
1483
1484 C<FdGetOsFHandle> simply calls C<_get_osfhandle()>.  It was renamed
1485 to better fit in with the rest the function names of this module,
1486 in particular to distinguish it from C<GetOsFHandle>.  It takes an
1487 integer file descriptor [as from Perl's C<fileno>] and returns the
1488 Win32 native file handle associated with that file descriptor or
1489 C<INVALID_HANDLE_VALUE> if C<$ivFd> is not an open file descriptor.
1490
1491 When you call Perl's C<open> to set a Perl file handle [like C<STDOUT>],
1492 Perl calls C's C<fopen> to set a stdio C<FILE *>.  C's C<fopen> calls
1493 something like Unix's C<open>, that is, Win32's C<_sopen>, to get an
1494 integer file descriptor [where 0 is for C<STDIN>, 1 for C<STDOUT>, etc.].
1495 Win32's C<_sopen> calls C<CreateFile> to set a C<HANDLE>, a Win32 native
1496 file handle.  So every Perl file handle [like C<STDOUT>] has an integer
1497 file descriptor associated with it that you can get via C<fileno>.  And,
1498 under Win32, every file descriptor has a Win32 native file handle
1499 associated with it.  C<FdGetOsFHandle> lets you get access to that.
1500
1501 C<$hNativeHandle> is set to C<INVALID_HANDLE_VALUE> [and
1502 C<lastFileError()> and C<$^E> are set] if C<FdGetOsFHandle> fails.
1503 See also C<GetOsFHandle> which provides a friendlier interface.
1504
1505 =item fileConstant
1506
1507 =item C<$value= fileConstant( $sConstantName )>
1508
1509 Fetch the value of a constant.  Returns C<undef> if C<$sConstantName>
1510 is not the name of a constant supported by this module.  Never sets
1511 C<$!> nor C<$^E>.
1512
1513 This function is rarely used since you will usually get the value of a
1514 constant by having that constant imported into your package by listing
1515 the constant name in the C<use Win32API::File> statement and then
1516 simply using the constant name in your code [perhaps followed by
1517 C<()>].  This function is useful for verifying constant names not in
1518 Perl code, for example, after prompting a user to type in a constant
1519 name.
1520
1521 =item fileLastError
1522
1523 =item C<$svError= fileLastError();>
1524
1525 =item C<fileLastError( $uError );>
1526
1527 Returns the last error encountered by a routine from this module.
1528 It is just like C<$^E> except it isn't changed by anything except
1529 routines from this module.  Ideally you could just use C<$^E>, but
1530 current versions of Perl often overwrite C<$^E> before you get a
1531 chance to check it and really old versions of Perl don't really
1532 support C<$^E> under Win32.
1533
1534 Just like C<$^E>, in a numeric context C<fileLastError()> returns
1535 the numeric error value while in a string context it returns a
1536 text description of the error [actually it returns a Perl scalar
1537 that contains both values so C<$x= fileLastError()> causes C<$x>
1538 to give different values in string vs. numeric contexts].
1539
1540 The last form sets the error returned by future calls to
1541 C<fileLastError()> and should not be used often.  C<$uError> must
1542 be a numeric error code.  Also returns the dual-valued version
1543 of C<$uError>.
1544
1545 =item GetDriveType
1546
1547 =item C<$uDriveType= GetDriveType( $sRootPath )>
1548
1549 Takes a string giving the path to the root directory of a file system
1550 [called a "drive" because every file system is assigned a "drive letter"]
1551 and returns an unsigned value indicating the type of drive the file
1552 system is on.  The return value should be one of:
1553
1554 =over
1555
1556 =item C<DRIVE_UNKNOWN>
1557
1558 None of the following.
1559
1560 =item C<DRIVE_NO_ROOT_DIR>
1561
1562 A "drive" that does not have a file system.  This can be a drive letter
1563 that hasn't been defined or a drive letter assigned to a partition
1564 that hasn't been formatted yet.
1565
1566 =item C<DRIVE_REMOVABLE>
1567
1568 A floppy diskette drive or other removable media drive, but not a CD-ROM
1569 drive.
1570
1571 =item C<DRIVE_FIXED>
1572
1573 An ordinary hard disk partition.
1574
1575 =item C<DRIVE_REMOTE>
1576
1577 A network share.
1578
1579 =item C<DRIVE_CDROM>
1580
1581 A CD-ROM drive.
1582
1583 =item C<DRIVE_RAMDISK>
1584
1585 A "ram disk" or memory-resident virtual file system used for high-speed
1586 access to small amounts of temporary file space.
1587
1588 =back
1589
1590 =item GetFileAttributes
1591
1592 =item C<$uAttrs = GetFileAttributes( $sPath )>
1593
1594 Takes a path string and returns an unsigned value with attribute flags.
1595 If it fails, it returns INVALID_FILE_ATTRIBUTES, otherwise it can be
1596 one or more of the following values:
1597
1598 =over
1599
1600 =item C<FILE_ATTRIBUTE_ARCHIVE>
1601
1602 The file or directory is an archive file or directory. Applications use
1603 this attribute to mark files for backup or removal.
1604
1605 =item C<FILE_ATTRIBUTE_COMPRESSED>
1606
1607 The file or directory is compressed. For a file, this means that all of
1608 the data in the file is compressed. For a directory, this means that
1609 compression is the default for newly created files and subdirectories.
1610
1611 =item C<FILE_ATTRIBUTE_DEVICE>
1612
1613 Reserved; do not use.
1614
1615 =item C<FILE_ATTRIBUTE_DIRECTORY>
1616
1617 The handle identifies a directory.
1618
1619 =item C<FILE_ATTRIBUTE_ENCRYPTED>
1620
1621 The file or directory is encrypted. For a file, this means that all data
1622 streams in the file are encrypted. For a directory, this means that
1623 encryption is the default for newly created files and subdirectories.
1624
1625 =item C<FILE_ATTRIBUTE_HIDDEN>
1626
1627 The file or directory is hidden. It is not included in an ordinary directory
1628 listing.
1629
1630 =item C<FILE_ATTRIBUTE_NORMAL>
1631
1632 The file or directory has no other attributes set. This attribute is valid
1633 only if used alone.
1634
1635 =item C<FILE_ATTRIBUTE_NOT_CONTENT_INDEXED>
1636
1637 The file will not be indexed by the content indexing service.
1638
1639 =item C<FILE_ATTRIBUTE_OFFLINE>
1640
1641 The data of the file is not immediately available. This attribute indicates
1642 that the file data has been physically moved to offline storage. This
1643 attribute is used by Remote Storage, the hierarchical storage management
1644 software. Applications should not arbitrarily change this attribute.
1645
1646 =item C<FILE_ATTRIBUTE_READONLY>
1647
1648 The file or directory is read-only. Applications can read the file but cannot
1649 write to it or delete it. In the case of a directory, applications cannot
1650 delete it.
1651
1652 =item C<FILE_ATTRIBUTE_REPARSE_POINT>
1653
1654 The file or directory has an associated reparse point.
1655
1656 =item C<FILE_ATTRIBUTE_SPARSE_FILE>
1657
1658 The file is a sparse file.
1659
1660 =item C<FILE_ATTRIBUTE_SYSTEM>
1661
1662 The file or directory is part of, or is used exclusively by, the operating
1663 system.
1664
1665 =item C<FILE_ATTRIBUTE_TEMPORARY>
1666
1667 The file is being used for temporary storage. File systems avoid writing
1668 data back to mass storage if sufficient cache memory is available, because
1669 often the application deletes the temporary file shortly after the handle is
1670 closed. In that case, the system can entirely avoid writing the data.
1671 Otherwise, the data will be written after the handle is closed.
1672
1673 =back
1674
1675 =item GetFileType
1676
1677 =item C<$uFileType= GetFileType( $hFile )>
1678
1679 Takes a Win32 native file handle and returns a C<FILE_TYPE_*> constant
1680 indicating the type of the file opened on that handle:
1681
1682 =over
1683
1684 =item C<FILE_TYPE_UNKNOWN>
1685
1686 None of the below.  Often a special device.
1687
1688 =item C<FILE_TYPE_DISK>
1689
1690 An ordinary disk file.
1691
1692 =item C<FILE_TYPE_CHAR>
1693
1694 What Unix would call a "character special file", that is, a device that
1695 works on character streams such as a printer port or a console.
1696
1697 =item C<FILE_TYPE_PIPE>
1698
1699 Either a named or anonymous pipe.
1700
1701 =back
1702
1703 =item getFileSize
1704
1705 =item C<$size= getFileSize( $hFile )>
1706
1707 This is a Perl-friendly wrapper for the C<GetFileSize> (below) API call.
1708
1709 It takes a Win32 native file handle and returns the size in bytes. Since the
1710 size can be a 64 bit value, on non 64 bit integer Perls the value returned will
1711 be an object of type C<Math::BigInt>.
1712
1713 =item GetFileSize
1714
1715 =item C<$iSizeLow= GetFileSize($win32Handle, $iSizeHigh)>
1716
1717 Returns the size of a file pointed to by C<$win32Handle>, optionally storing
1718 the high order 32 bits into C<$iSizeHigh> if it is not C<[]>. If $iSizeHigh is
1719 C<[]>, a non-zero value indicates success. Otherwise, on failure the return
1720 value will be C<0xffffffff> and C<fileLastError()> will not be C<NO_ERROR>.
1721
1722 =item GetOverlappedResult
1723
1724 =item C<$bRetval= GetOverlappedResult( $win32Handle, $pOverlapped,
1725  $numBytesTransferred, $bWait )>
1726
1727 Used for asynchronous IO in Win32 to get the result of a pending IO operation,
1728 such as when a file operation returns C<ERROR_IO_PENDING>. Returns a false
1729 value on failure. The C<$overlapped> structure and C<$numBytesTransferred>
1730 will be modified with the results of the operation.
1731
1732 As far as creating the C<$pOverlapped> structure, you are currently on your own.
1733
1734 See L<http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dllproc/base/getoverlappedresult.asp> for more information.
1735
1736 =item GetLogicalDrives
1737
1738 =item C<$uDriveBits= GetLogicalDrives()>
1739
1740 Returns an unsigned value with one bit set for each drive letter currently
1741 defined.  If "A:" is currently a valid drive letter, then the C<1> bit
1742 will be set in C<$uDriveBits>.  If "B:" is valid, then the C<2> bit will
1743 be set.  If "Z:" is valid, then the C<2**26> [C<0x4000000>] bit will be
1744 set.
1745
1746 =item GetLogicalDriveStrings
1747
1748 =item C<$olOutLength= GetLogicalDriveStrings( $lBufSize, $osBuffer )>
1749
1750 For each currently defined drive letter, a C<'\0'>-terminated string
1751 of the path to the root of its file system is constructed.  All of
1752 these strings are concatenated into a single larger string and an
1753 extra terminating C<'\0'> is added.  This larger string is returned
1754 in C<$osBuffer>.  Note that this includes drive letters that have
1755 been defined but that have no file system, such as drive letters
1756 assigned to unformatted partitions.
1757
1758 C<$lBufSize> is the size of the buffer to allocate to store this
1759 list of strings.  C<26*4+1> is always sufficient and should usually
1760 be used.
1761
1762 C<$osBuffer> is a scalar to be set to contain the constructed string.
1763
1764 C<$olOutLength> is the number of bytes actually written to C<$osBuffer>
1765 but C<length($osBuffer)> can also be used to determine this.
1766
1767 For example, on a poorly equipped computer,
1768
1769     GetLogicalDriveStrings( 4*26+1, $osBuffer );
1770
1771 might set C<$osBuffer> to the 9-character string, C<"A:\\\0C:\\\0\0">.
1772
1773 =item GetHandleInformation
1774
1775 =item C<GetHandleInformation( $hObject, $ouFlags )>
1776
1777 Retrieves the flags associated with a Win32 native file handle or object
1778 handle.
1779
1780 C<$hObject> is an open Win32 native file handle or an open Win32 native
1781 handle to some other type of object.
1782
1783 C<$ouFlags> will be set to an unsigned value having zero or more of
1784 the bits C<HANDLE_FLAG_INHERIT> and C<HANDLE_FLAG_PROTECT_FROM_CLOSE>
1785 set.  See the C<":HANDLE_FLAG_"> export class for the meanings of these
1786 bits.
1787
1788 =item GetOsFHandle
1789
1790 =item C<$hNativeHandle= GetOsFHandle( FILE )>
1791
1792 Takes a Perl file handle [like C<STDIN>] and returns the Win32 native
1793 file handle associated with it.  See C<FdGetOsFHandle> for more
1794 information about Win32 native file handles.
1795
1796 C<$hNativeHandle> is set to a false value [and C<lastFileError()> and
1797 C<$^E> are set] if C<GetOsFHandle> fails.    C<GetOsFHandle> returns
1798 C<"0 but true"> in the impossible(?) case of the handle having a value
1799 of C<0>.
1800
1801 =item GetVolumeInformation
1802
1803 =item C<GetVolumeInformation( $sRootPath, $osVolName, $lVolName, $ouSerialNum, $ouMaxNameLen, $ouFsFlags, $osFsType, $lFsType )>
1804
1805 Gets information about a file system volume, returning a true
1806 value if successful.  On failure, returns a false value and sets
1807 C<fileLastError()> and C<$^E>.
1808
1809 C<$sRootPath> is a string specifying the path to the root of the file system,
1810 for example, C<"C:/">.
1811
1812 C<$osVolName> is a scalar to be set to the string representing the
1813 volume name, also called the file system label.  C<$lVolName> is the
1814 number of bytes to allocate for the C<$osVolName> buffer [see
1815 L<Buffer Sizes> for more information].
1816
1817 C<$ouSerialNum> is C<[]> [for C<NULL>] or will be set to the numeric
1818 value of the volume's serial number.
1819
1820 C<$ouMaxNameLen> is C<[]> [for C<NULL>] or will be set to the maximum
1821 length allowed for a file name or directory name within the file system.
1822
1823 C<$osFsType> is a scalar to be set to the string representing the
1824 file system type, such as C<"FAT"> or C<"NTFS">.  C<$lFsType> is the
1825 number of bytes to allocate for the C<$osFsType> buffer [see
1826 L<Buffer Sizes> for more information].
1827
1828 C<$ouFsFlags> is C<[]> [for C<NULL>] or will be set to an unsigned integer
1829 with bits set indicating properties of the file system:
1830
1831 =over
1832
1833 =item C<FS_CASE_IS_PRESERVED>
1834
1835 The file system preserves the case of file names [usually true].
1836 That is, it doesn't change the case of file names such as forcing
1837 them to upper- or lower-case.
1838
1839 =item C<FS_CASE_SENSITIVE>
1840
1841 The file system supports the ability to not ignore the case of file
1842 names [but might ignore case the way you are using it].  That is, the
1843 file system has the ability to force you to get the letter case of a
1844 file's name exactly right to be able to open it.  This is true for
1845 "NTFS" file systems, even though case in file names is usually still
1846 ignored.
1847
1848 =item C<FS_UNICODE_STORED_ON_DISK>
1849
1850 The file system preserves Unicode in file names [true for "NTFS"].
1851
1852 =item C<FS_PERSISTENT_ACLS>
1853
1854 The file system supports setting Access Control Lists on files [true
1855 for "NTFS"].
1856
1857 =item C<FS_FILE_COMPRESSION>
1858
1859 The file system supports compression on a per-file basis [true for
1860 "NTFS"].
1861
1862 =item C<FS_VOL_IS_COMPRESSED>
1863
1864 The entire file system is compressed such as via "DoubleSpace".
1865
1866 =back
1867
1868 =item IsRecognizedPartition
1869
1870 =item C<IsRecognizedPartition( $ivPartitionType )>
1871
1872 Takes a partition type and returns whether that partition type is
1873 supported under Win32.  C<$ivPartitonType> is an integer value as from
1874 the operating system byte of a hard disk's DOS-compatible partition
1875 table [that is, a partition table for x86-based Win32, not, for
1876 example, one used with Windows NT for Alpha processors].  For example,
1877 the C<PartitionType> member of the C<PARTITION_INFORMATION> structure.
1878
1879 Common values for C<$ivPartitionType> include C<PARTITION_FAT_12==1>,
1880 C<PARTITION_FAT_16==4>, C<PARTITION_EXTENDED==5>, C<PARTITION_FAT32==0xB>.
1881
1882 =item IsContainerPartition
1883
1884 =item C<IsContainerPartition( $ivPartitionType )>
1885
1886 Takes a partition type and returns whether that partition is a
1887 "container" partition that is supported under Win32, that is, whether
1888 it is an "extended" partition that can contain "logical" partitions.
1889 C<$ivPartitonType> is as for C<IsRecognizedPartition>.
1890
1891 =item MoveFile
1892
1893 =item C<MoveFile( $sOldName, $sNewName )>
1894
1895 Renames a file or directory.  C<$sOldName> is the name of the existing
1896 file or directory that is to be renamed.  C<$sNewName> is the new name
1897 to give the file or directory.  Returns a true value if the move
1898 succeeds.  For failure, returns a false value and sets
1899 C<fileLastErorr()> and C<$^E> to the reason for the failure.
1900
1901 Files can be "renamed" between file systems and the file contents and
1902 some attributes will be moved.  Directories can only be renamed within
1903 one file system.  If there is already a file or directory named
1904 C<$sNewName>, then C<MoveFile> will fail.
1905
1906 =item MoveFileEx
1907
1908 =item C<MoveFileEx( $sOldName, $sNewName, $uFlags )>
1909
1910 Renames a file or directory.  C<$sOldName> is the name of the existing
1911 file or directory that is to be renamed.  C<$sNewName> is the new name
1912 to give the file or directory.  Returns a true value if the move
1913 succeeds.  For failure, returns a false value and sets
1914 C<fileLastErorr()> and C<$^E> to the reason for the failure.
1915
1916 C<$uFlags> is an unsigned value with zero or more of the following bits set:
1917
1918 =over
1919
1920 =item C<MOVEFILE_REPLACE_EXISTING>
1921
1922 If this bit is set and a file [but not a directory] named C<$sNewName>
1923 already exists, then it will be replaced by C<$sOldName>.  If this bit
1924 is not set then C<MoveFileEx> will fail rather than replace an existing
1925 C<$sNewName>.
1926
1927 =item C<MOVEFILE_COPY_ALLOWED>
1928
1929 Allows files [but not directories] to be moved between file systems
1930 by copying the C<$sOldName> file data and some attributes to
1931 C<$sNewName> and then deleting C<$sOldName>.  If this bit is not set
1932 [or if C<$sOldName> denotes a directory] and C<$sNewName> refers to a
1933 different file system than C<$sOldName>, then C<MoveFileEx> will fail.
1934
1935 =item C<MOVEFILE_DELAY_UNTIL_REBOOT>
1936
1937 Preliminary verifications are made and then an entry is added to the
1938 Registry to cause the rename [or delete] operation to be done the
1939 next time this copy of the operating system is booted [right after
1940 any automatic file system checks have completed].  This is not
1941 supported under Windows 95.
1942
1943 When this bit is set, C<$sNewName> can be C<[]> [for C<NULL>] to
1944 indicate that C<$sOldName> should be deleted during the next boot
1945 rather than renamed.
1946
1947 Setting both the C<MOVEFILE_COPY_ALLOWED> and
1948 C<MOVEFILE_DELAY_UNTIL_REBOOT> bits will cause C<MoveFileEx> to fail.
1949
1950 =item C<MOVEFILE_WRITE_THROUGH>
1951
1952 Ensures that C<MoveFileEx> won't return until the operation has
1953 finished and been flushed to disk.   This is not supported under
1954 Windows 95.  Only affects file renames to another file system,
1955 forcing a buffer flush at the end of the copy operation.
1956
1957 =back
1958
1959 =item OsFHandleOpen
1960
1961 =item C<OsFHandleOpen( FILE, $hNativeHandle, $sMode )>
1962
1963 Opens a Perl file handle based on an already open Win32 native
1964 file handle [much like C's C<fdopen()> does with a file descriptor].
1965 Returns a true value if the open operation succeeded.  For failure,
1966 returns a false value and sets C<$!> [and possibly C<fileLastError()>
1967 and C<$^E>] to the reason for the failure.
1968
1969 C<FILE> is a Perl file handle [in any of the supported forms, a
1970 bareword, a string, a typeglob, or a reference to a typeglob] that
1971 will be opened.  If C<FILE> is already open, it will automatically
1972 be closed before it is reopened.
1973
1974 C<$hNativeHandle> is an open Win32 native file handle, probably the
1975 return value from C<CreateFile> or C<createFile>.
1976
1977 C<$sMode> is string of zero or more letters from C<"rwatb">.  These
1978 are translated into a combination C<O_RDONLY> [C<"r">], C<O_WRONLY>
1979 [C<"w">], C<O_RDWR> [C<"rw">], C<O_APPEND> [C<"a">], C<O_TEXT>
1980 [C<"t">], and C<O_BINARY> [C<"b">] flags [see the L<Fcntl> module]
1981 that is passed to C<OsFHandleOpenFd>.   Currently only C<O_APPEND>
1982 and C<O_TEXT> have any significance.
1983
1984 Also, a C<"r"> and/or C<"w"> in C<$sMode> is used to decide how the
1985 file descriptor is converted into a Perl file handle, even though this
1986 doesn't appear to make a difference.  One of the following is used:
1987
1988     open( FILE, "<&=".$ivFd )   # "r" w/o "w"
1989     open( FILE, ">&=".$ivFd )   # "w" w/o "r"
1990     open( FILE, "+<&=".$ivFd )  # both "r" and "w"
1991
1992 C<OsFHandleOpen> eventually calls the Win32-specific C routine
1993 C<_open_osfhandle()> or Perl's "improved" version called
1994 C<win32_open_osfhandle()>.  Prior to Perl5.005, C's
1995 C<_open_osfhandle()> is called which will fail if
1996 C<GetFileType($hNativeHandle)> would return C<FILE_TYPE_UNKNOWN>.  For
1997 Perl5.005 and later, C<OsFHandleOpen> calls C<win32_open_osfhandle()>
1998 from the Perl DLL which doesn't have this restriction.
1999
2000 =item OsFHandleOpenFd
2001
2002 =item C<$ivFD= OsFHandleOpenFd( $hNativeHandle, $uMode )>
2003
2004 Opens a file descriptor [C<$ivFD>] based on an already open Win32
2005 native file handle, C<$hNativeHandle>.  This just calls the
2006 Win32-specific C routine C<_open_osfhandle()> or Perl's "improved"
2007 version called C<win32_open_osfhandle()>.  Prior to Perl5.005 and in Cygwin
2008 Perl, C's C<_open_osfhandle()> is called which will fail if
2009 C<GetFileType($hNativeHandle)> would return C<FILE_TYPE_UNKNOWN>.  For
2010 Perl5.005 and later, C<OsFHandleOpenFd> calls C<win32_open_osfhandle()> from
2011 the Perl DLL which doesn't have this restriction.
2012
2013 C<$uMode> the logical combination of zero or more C<O_*> constants
2014 exported by the C<Fcntl> module.  Currently only C<O_APPEND> and
2015 C<O_TEXT> have any significance.
2016
2017 C<$ivFD> will be non-negative if the open operation was successful.
2018 For failure, C<-1> is returned and C<$!> [and possibly
2019 C<fileLastError()> and C<$^E>] is set to the reason for the failure.
2020
2021 =item QueryDosDevice
2022
2023 =item C<$olTargetLen= QueryDosDevice( $sDosDeviceName, $osTargetPath, $lTargetBuf )>
2024
2025 Looks up the definition of a given "DOS" device name, yielding the
2026 active Windows NT native device name along with any currently dormant
2027 definitions.
2028
2029 C<$sDosDeviceName> is the name of the "DOS" device whose definitions
2030 we want.  For example, C<"C:">, C<"COM1">, or C<"PhysicalDrive0">.
2031 If C<$sDosDeviceName> is C<[]> [for C<NULL>], the list of all DOS
2032 device names is returned instead.
2033
2034 C<$osTargetPath> will be assigned a string containing the list of
2035 definitions.  The definitions are each C<'\0'>-terminate and are
2036 concatenated into the string, most recent first, with an extra C<'\0'>
2037 at the end of the whole string [see C<GetLogicalDriveStrings> for
2038 a sample of this format].
2039
2040 C<$lTargetBuf> is the size [in bytes] of the buffer to allocate for
2041 C<$osTargetPath>.  See L<Buffer Sizes> for more information.
2042
2043 C<$olTargetLen> is set to the number of bytes written to
2044 C<$osTargetPath> but you can also use C<length($osTargetPath)>
2045 to determine this.
2046
2047 For failure, C<0> is returned and C<fileLastError()> and C<$^E> are
2048 set to the reason for the failure.
2049
2050 =item ReadFile
2051
2052 =item C<ReadFile( $hFile, $opBuffer, $lBytes, $olBytesRead, $pOverlapped )>
2053
2054 Reads bytes from a file or file-like device.  Returns a true value if
2055 the read operation was successful.  For failure, returns a false value
2056 and sets C<fileLastError()> and C<$^E> for the reason for the failure.
2057
2058 C<$hFile> is a Win32 native file handle that is already open to the
2059 file or device to read from.
2060
2061 C<$opBuffer> will be set to a string containing the bytes read.
2062
2063 C<$lBytes> is the number of bytes you would like to read.
2064 C<$opBuffer> is automatically initialized to have a buffer large
2065 enough to hold that many bytes.  Unlike other buffer sizes, C<$lBytes>
2066 does not need to have a C<"="> prepended to it to prevent a larger
2067 value to be passed to the underlying Win32 C<ReadFile> API.  However,
2068 a leading C<"="> will be silently ignored, even if Perl warnings are
2069 enabled.
2070
2071 If C<$olBytesRead> is not C<[]>, it will be set to the actual number
2072 of bytes read, though C<length($opBuffer)> can also be used to
2073 determine this.
2074
2075 C<$pOverlapped> is C<[]> or is a C<OVERLAPPED> structure packed
2076 into a string.  This is only useful if C<$hFile> was opened with
2077 the C<FILE_FLAG_OVERLAPPED> flag set.
2078
2079 =item SetErrorMode
2080
2081 =item C<$uOldMode= SetErrorMode( $uNewMode )>
2082
2083 Sets the mode controlling system error handling B<and> returns the
2084 previous mode value.  Both C<$uOldMode> and C<$uNewMode> will have
2085 zero or more of the following bits set:
2086
2087 =over
2088
2089 =item C<SEM_FAILCRITICALERRORS>
2090
2091 If set, indicates that when a critical error is encountered, the call
2092 that triggered the error fails immediately.  Normally this bit is not
2093 set, which means that a critical error causes a dialogue box to appear
2094 notifying the desktop user that some application has triggered a
2095 critical error.   The dialogue box allows the desktop user to decide
2096 whether the critical error is returned to the process, is ignored, or
2097 the offending operation is retried.
2098
2099 This affects the C<CreateFile> and C<GetVolumeInformation> calls.
2100
2101 Setting this bit is useful for allowing you to check whether a floppy
2102 diskette is in the floppy drive.
2103
2104 =item C<SEM_NOALIGNMENTFAULTEXCEPT>
2105
2106 If set, this causes memory access misalignment faults to be
2107 automatically fixed in a manner invisible to the process.  This flag
2108 is ignored on x86-based versions of Windows NT.  This flag is not
2109 supported on Windows 95.
2110
2111 =item C<SEM_NOGPFAULTERRORBOX>
2112
2113 If set, general protection faults do not generate a dialogue box but
2114 can instead be handled by the process via an exception handler.  This
2115 bit should not be set by programs that don't know how to handle such
2116 faults.
2117
2118 =item C<SEM_NOOPENFILEERRORBOX>
2119
2120 If set, then when an attempt to continue reading from or writing to
2121 an already open file [usually on a removable medium like a floppy
2122 diskette] finds the file no longer available, the call will
2123 immediately fail.  Normally this bit is not set, which means that
2124 instead a dialogue box will appear notifying the desktop user that
2125 some application has run into this problem.   The dialogue box allows
2126 the desktop user to decide whether the failure is returned to the
2127 process, is ignored, or the offending operation is retried.
2128
2129 This affects the C<ReadFile> and C<WriteFile> calls.
2130
2131 =back
2132
2133 =item setFilePointer
2134
2135 =item C<$uNewPos = setFilePointer( $hFile, $ivOffset, $uFromWhere )>
2136
2137 This is a perl-friendly wrapper for the SetFilePointer API (below).
2138 C<$ivOffset> can be a 64 bit integer or C<Math::BigInt> object if your Perl
2139 doesn't have 64 bit integers. The return value is the new offset and will
2140 likewise be a 64 bit integer or a C<Math::BigInt> object.
2141
2142 =item SetFilePointer
2143
2144 =item C<$uNewPos = SetFilePointer( $hFile, $ivOffset, $ioivOffsetHigh, $uFromWhere )>
2145
2146 The native Win32 version of C<seek()>.  C<SetFilePointer> sets the
2147 position within a file where the next read or write operation will
2148 start from.
2149
2150 C<$hFile> is a Win32 native file handle.
2151
2152 C<$uFromWhere> is either C<FILE_BEGIN>, C<FILE_CURRENT>, or
2153 C<FILE_END>, indicating that the new file position is being specified
2154 relative to the beginning of the file, the current file pointer, or
2155 the end of the file, respectively.
2156
2157 C<$ivOffset> is [if C<$ioivOffsetHigh> is C<[]>] the offset [in bytes]
2158 to the new file position from the position specified via
2159 C<$uFromWhere>.  If C<$ioivOffsetHigh> is not C<[]>, then C<$ivOffset>
2160 is converted to an unsigned value to be used as the low-order 4 bytes
2161 of the offset.
2162
2163 C<$ioivOffsetHigh> can be C<[]> [for C<NULL>] to indicate that you are
2164 only specifying a 4-byte offset and the resulting file position will
2165 be 0xFFFFFFFE or less [just under 4GB].  Otherwise C<$ioivOfffsetHigh>
2166 starts out with the high-order 4 bytes [signed] of the offset and gets
2167 set to the [unsigned] high-order 4 bytes of the resulting file position.
2168
2169 The underlying C<SetFilePointer> returns C<0xFFFFFFFF> to indicate
2170 failure, but if C<$ioivOffsetHigh> is not C<[]>, you would also have
2171 to check C<$^E> to determine whether C<0xFFFFFFFF> indicates an error
2172 or not.  C<Win32API::File::SetFilePointer> does this checking for you
2173 and returns a false value if and only if the underlying
2174 C<SetFilePointer> failed.  For this reason, C<$uNewPos> is set to
2175 C<"0 but true"> if you set the file pointer to the beginning of the
2176 file [or any position with 0 for the low-order 4 bytes].
2177
2178 So the return value will be true if the seek operation was successful.
2179 For failure, a false value is returned and C<fileLastError()> and
2180 C<$^E> are set to the reason for the failure.
2181
2182 =item SetHandleInformation
2183
2184 =item C<SetHandleInformation( $hObject, $uMask, $uFlags )>
2185
2186 Sets the flags associated with a Win32 native file handle or object
2187 handle.  Returns a true value if the operation was successful.  For
2188 failure, returns a false value and sets C<fileLastError()> and C<$^E>
2189 for the reason for the failure.
2190
2191 C<$hObject> is an open Win32 native file handle or an open Win32 native
2192 handle to some other type of object.
2193
2194 C<$uMask> is an unsigned value having one or more of the bits
2195 C<HANDLE_FLAG_INHERIT> and C<HANDLE_FLAG_PROTECT_FROM_CLOSE> set.
2196 Only bits set in C<$uMask> will be modified by C<SetHandleInformation>.
2197
2198 C<$uFlags> is an unsigned value having zero or more of the bits
2199 C<HANDLE_FLAG_INHERIT> and C<HANDLE_FLAG_PROTECT_FROM_CLOSE> set.
2200 For each bit set in C<$uMask>, the cooresponding bit in the handle's
2201 flags is set to the value of the corresponding bit in C<$uFlags>.
2202
2203 If C<$uOldFlags> were the value of the handle's flags before the
2204 call to C<SetHandleInformation>, then the value of the handle's
2205 flags afterward would be:
2206
2207     ( $uOldFlags & ~$uMask ) | ( $uFlags & $uMask )
2208
2209 [at least as far as the C<HANDLE_FLAG_INHERIT> and
2210 C<HANDLE_FLAG_PROTECT_FROM_CLOSE> bits are concerned.]
2211
2212 See the C<":HANDLE_FLAG_"> export class for the meanings of these bits.
2213
2214 =item WriteFile
2215
2216 =item C<WriteFile( $hFile, $pBuffer, $lBytes, $ouBytesWritten, $pOverlapped )>
2217
2218 Write bytes to a file or file-like device.  Returns a true value if
2219 the operation was successful.  For failure, returns a false value and
2220 sets C<fileLastError()> and C<$^E> for the reason for the failure.
2221
2222 C<$hFile> is a Win32 native file handle that is already open to the
2223 file or device to be written to.
2224
2225 C<$pBuffer> is a string containing the bytes to be written.
2226
2227 C<$lBytes> is the number of bytes you would like to write.  If
2228 C<$pBuffer> is not at least C<$lBytes> long, C<WriteFile> croaks.  You
2229 can specify C<0> for C<$lBytes> to write C<length($pBuffer)> bytes.
2230 A leading C<"="> on C<$lBytes> will be silently ignored, even if Perl
2231 warnings are enabled.
2232
2233 C<$ouBytesWritten> will be set to the actual number of bytes written
2234 unless you specify it as C<[]>.
2235
2236 C<$pOverlapped> is C<[]> or is an C<OVERLAPPED> structure packed
2237 into a string.  This is only useful if C<$hFile> was opened with
2238 the C<FILE_FLAG_OVERLAPPED> flag set.
2239
2240 =back
2241
2242 =item C<":FuncA">
2243
2244 The ASCII-specific functions.  Each of these is just the same as the
2245 version without the trailing "A".
2246
2247         CopyFileA
2248         CreateFileA
2249         DefineDosDeviceA
2250         DeleteFileA
2251         GetDriveTypeA
2252         GetFileAttributesA
2253         GetLogicalDriveStringsA
2254         GetVolumeInformationA
2255         MoveFileA
2256         MoveFileExA
2257         QueryDosDeviceA
2258
2259 =item C<":FuncW">
2260
2261 The wide-character-specific (Unicode) functions.  Each of these is
2262 just the same as the version without the trailing "W" except that
2263 strings are expected in Unicode and some lengths are measured as
2264 number of C<WCHAR>s instead of number of bytes, as indicated below.
2265
2266 =over
2267
2268 =item CopyFileW
2269
2270 =item C<CopyFileW( $swOldFileName, $swNewFileName, $bFailIfExists )>
2271
2272 C<$swOldFileName> and C<$swNewFileName> are Unicode strings.
2273
2274 =item CreateFileW
2275
2276 =item C<$hObject= CreateFileW( $swPath, $uAccess, $uShare, $pSecAttr, $uCreate, $uFlags, $hModel )>
2277
2278 C<$swPath> is Unicode.
2279
2280 =item DefineDosDeviceW
2281
2282 =item C<DefineDosDeviceW( $uFlags, $swDosDeviceName, $swTargetPath )>
2283
2284 C<$swDosDeviceName> and C<$swTargetPath> are Unicode.
2285
2286 =item DeleteFileW
2287
2288 =item C<DeleteFileW( $swFileName )>
2289
2290 C<$swFileName> is Unicode.
2291
2292 =item GetDriveTypeW
2293
2294 =item C<$uDriveType= GetDriveTypeW( $swRootPath )>
2295
2296 C<$swRootPath> is Unicode.
2297
2298 =item GetFileAttributesW
2299
2300 =item C<$uAttrs= GetFileAttributesW( $swPath )>
2301
2302 C<$swPath> is Unicode.
2303
2304 =item GetLogicalDriveStringsW
2305
2306 =item C<$olwOutLength= GetLogicalDriveStringsW( $lwBufSize, $oswBuffer )>
2307
2308 Unicode is stored in C<$oswBuffer>.  C<$lwBufSize> and C<$olwOutLength>
2309 are measured as number of C<WCHAR>s.
2310
2311 =item GetVolumeInformationW
2312
2313 =item C<GetVolumeInformationW( $swRootPath, $oswVolName, $lwVolName, $ouSerialNum, $ouMaxNameLen, $ouFsFlags, $oswFsType, $lwFsType )>
2314
2315 C<$swRootPath> is Unicode and Unicode is written to C<$oswVolName> and
2316 C<$oswFsType>.  C<$lwVolName> and C<$lwFsType> are measures as number
2317 of C<WCHAR>s.
2318
2319 =item MoveFileW
2320
2321 =item C<MoveFileW( $swOldName, $swNewName )>
2322
2323 C<$swOldName> and C<$swNewName> are Unicode.
2324
2325 =item MoveFileExW
2326
2327 =item C<MoveFileExW( $swOldName, $swNewName, $uFlags )>
2328
2329 C<$swOldName> and C<$swNewName> are Unicode.
2330
2331 =item QueryDosDeviceW
2332
2333 =item C<$olwTargetLen= QueryDosDeviceW( $swDeviceName, $oswTargetPath, $lwTargetBuf )>
2334
2335 C<$swDeviceName> is Unicode and Unicode is written to
2336 C<$oswTargetPath>.  C<$lwTargetBuf> and C<$olwTargetLen> are measured
2337 as number of  C<WCHAR>s.
2338
2339 =back
2340
2341 =item C<":Misc">
2342
2343 Miscellaneous constants.  Used for the C<$uCreate> argument of
2344 C<CreateFile> or the C<$uFromWhere> argument of C<SetFilePointer>.
2345 Plus C<INVALID_HANDLE_VALUE>, which you usually won't need to check
2346 for since most routines translate it into a false value.
2347
2348         CREATE_ALWAYS           CREATE_NEW              OPEN_ALWAYS
2349         OPEN_EXISTING           TRUNCATE_EXISTING       INVALID_HANDLE_VALUE
2350         FILE_BEGIN              FILE_CURRENT            FILE_END
2351
2352 =item C<":DDD_">
2353
2354 Constants for the C<$uFlags> argument of C<DefineDosDevice>.
2355
2356         DDD_EXACT_MATCH_ON_REMOVE
2357         DDD_RAW_TARGET_PATH
2358         DDD_REMOVE_DEFINITION
2359
2360 =item C<":DRIVE_">
2361
2362 Constants returned by C<GetDriveType>.
2363
2364         DRIVE_UNKNOWN           DRIVE_NO_ROOT_DIR       DRIVE_REMOVABLE
2365         DRIVE_FIXED             DRIVE_REMOTE            DRIVE_CDROM
2366         DRIVE_RAMDISK
2367
2368 =item C<":FILE_">
2369
2370 Specific types of access to files that can be requested via the
2371 C<$uAccess> argument to C<CreateFile>.
2372
2373         FILE_READ_DATA                  FILE_LIST_DIRECTORY
2374         FILE_WRITE_DATA                 FILE_ADD_FILE
2375         FILE_APPEND_DATA                FILE_ADD_SUBDIRECTORY
2376         FILE_CREATE_PIPE_INSTANCE       FILE_READ_EA
2377         FILE_WRITE_EA                   FILE_EXECUTE
2378         FILE_TRAVERSE                   FILE_DELETE_CHILD
2379         FILE_READ_ATTRIBUTES            FILE_WRITE_ATTRIBUTES
2380         FILE_ALL_ACCESS                 FILE_GENERIC_READ
2381         FILE_GENERIC_WRITE              FILE_GENERIC_EXECUTE )],
2382
2383 =item C<":FILE_ATTRIBUTE_">
2384
2385 File attribute constants.  Returned by C<attrLetsToBits> and used in
2386 the C<$uFlags> argument to C<CreateFile>.
2387
2388         FILE_ATTRIBUTE_ARCHIVE                  FILE_ATTRIBUTE_COMPRESSED
2389         FILE_ATTRIBUTE_HIDDEN                   FILE_ATTRIBUTE_NORMAL
2390         FILE_ATTRIBUTE_OFFLINE                  FILE_ATTRIBUTE_READONLY
2391         FILE_ATTRIBUTE_SYSTEM                   FILE_ATTRIBUTE_TEMPORARY
2392
2393 In addition, C<GetFileAttributes> can return these constants (or
2394 INVALID_FILE_ATTRIBUTES in case of an error).
2395
2396         FILE_ATTRIBUTE_DEVICE                   FILE_ATTRIBUTE_DIRECTORY
2397         FILE_ATTRIBUTE_ENCRYPTED                FILE_ATTRIBUTE_NOT_CONTENT_INDEXED
2398         FILE_ATTRIBUTE_REPARSE_POINT    FILE_ATTRIBUTE_SPARSE_FILE
2399
2400 =item C<":FILE_FLAG_">
2401
2402 File option flag constants.  Used in the C<$uFlags> argument to
2403 C<CreateFile>.
2404
2405         FILE_FLAG_BACKUP_SEMANTICS      FILE_FLAG_DELETE_ON_CLOSE
2406         FILE_FLAG_NO_BUFFERING          FILE_FLAG_OVERLAPPED
2407         FILE_FLAG_POSIX_SEMANTICS       FILE_FLAG_RANDOM_ACCESS
2408         FILE_FLAG_SEQUENTIAL_SCAN       FILE_FLAG_WRITE_THROUGH
2409         FILE_FLAG_OPEN_REPARSE_POINT
2410
2411 =item C<":FILE_SHARE_">
2412
2413 File sharing constants.  Used in the C<$uShare> argument to
2414 C<CreateFile>.
2415
2416         FILE_SHARE_DELETE       FILE_SHARE_READ         FILE_SHARE_WRITE
2417
2418 =item C<":FILE_TYPE_">
2419
2420 File type constants.  Returned by C<GetFileType>.
2421
2422         FILE_TYPE_CHAR          FILE_TYPE_DISK
2423         FILE_TYPE_PIPE          FILE_TYPE_UNKNOWN
2424
2425 =item C<":FS_">
2426
2427 File system characteristics constants.  Placed in the C<$ouFsFlags>
2428 argument to C<GetVolumeInformation>.
2429
2430         FS_CASE_IS_PRESERVED            FS_CASE_SENSITIVE
2431         FS_UNICODE_STORED_ON_DISK       FS_PERSISTENT_ACLS
2432         FS_FILE_COMPRESSION             FS_VOL_IS_COMPRESSED
2433
2434 =item C<":HANDLE_FLAG_">
2435
2436 Flag bits modifying the behavior of an object handle and accessed via
2437 C<GetHandleInformation> and C<SetHandleInformation>.
2438
2439 =over
2440
2441 =item HANDLE_FLAG_INHERIT
2442
2443 If this bit is set, then children of this process who inherit handles
2444 [that is, processes created by calls to the Win32 C<CreateProcess> API
2445 with the C<bInheritHandles> parameter specified as C<TRUE>], will inherit
2446 this particular object handle.
2447
2448 =item HANDLE_FLAG_PROTECT_FROM_CLOSE
2449
2450 If this bit is set, then calls to C<CloseHandle> against this handle
2451 will be ignored, leaving the handle open and usable.
2452
2453 =back
2454
2455 =item C<":IOCTL_STORAGE_">
2456
2457 I/O control operations for generic storage devices.  Used in the
2458 C<$uIoControlCode> argument to C<DeviceIoControl>.  Includes
2459 C<IOCTL_STORAGE_CHECK_VERIFY>, C<IOCTL_STORAGE_MEDIA_REMOVAL>,
2460 C<IOCTL_STORAGE_EJECT_MEDIA>, C<IOCTL_STORAGE_LOAD_MEDIA>,
2461 C<IOCTL_STORAGE_RESERVE>, C<IOCTL_STORAGE_RELEASE>,
2462 C<IOCTL_STORAGE_FIND_NEW_DEVICES>, and
2463 C<IOCTL_STORAGE_GET_MEDIA_TYPES>.
2464
2465 =over
2466
2467 =item C<IOCTL_STORAGE_CHECK_VERIFY>
2468
2469 Verify that a device's media is accessible.  C<$pInBuf> and C<$opOutBuf>
2470 should both be C<[]>.  If C<DeviceIoControl> returns a true value, then
2471 the media is currently accessible.
2472
2473 =item C<IOCTL_STORAGE_MEDIA_REMOVAL>
2474
2475 Allows the device's media to be locked or unlocked.  C<$opOutBuf> should
2476 be C<[]>.  C<$pInBuf> should be a C<PREVENT_MEDIA_REMOVAL> data structure,
2477 which is simply an integer containing a boolean value:
2478
2479     $pInBuf= pack( "i", $bPreventMediaRemoval );
2480
2481 =item C<IOCTL_STORAGE_EJECT_MEDIA>
2482
2483 Requests that the device eject the media.  C<$pInBuf> and C<$opOutBuf>
2484 should both be C<[]>.
2485
2486 =item C<IOCTL_STORAGE_LOAD_MEDIA>
2487
2488 Requests that the device load the media.  C<$pInBuf> and C<$opOutBuf>
2489 should both be C<[]>.
2490
2491 =item C<IOCTL_STORAGE_RESERVE>
2492
2493 Requests that the device be reserved.  C<$pInBuf> and C<$opOutBuf>
2494 should both be C<[]>.
2495
2496 =item C<IOCTL_STORAGE_RELEASE>
2497
2498 Releases a previous device reservation.  C<$pInBuf> and C<$opOutBuf>
2499 should both be C<[]>.
2500
2501 =item C<IOCTL_STORAGE_FIND_NEW_DEVICES>
2502
2503 No documentation on this IOCTL operation was found.
2504
2505 =item C<IOCTL_STORAGE_GET_MEDIA_TYPES>
2506
2507 Requests information about the type of media supported by the device.
2508 C<$pInBuf> should be C<[]>.  C<$opOutBuf> will be set to contain a
2509 vector of C<DISK_GEOMETRY> data structures, which can be decoded via:
2510
2511     # Calculate the number of DISK_GEOMETRY structures returned:
2512     my $cStructs= length($opOutBuf)/(4+4+4+4+4+4);
2513     my @fields= unpack( "L l I L L L" x $cStructs, $opOutBuf )
2514     my( @ucCylsLow, @ivcCylsHigh, @uMediaType, @uTracksPerCyl,
2515       @uSectsPerTrack, @uBytesPerSect )= ();
2516     while(  @fields  ) {
2517         push( @ucCylsLow, unshift @fields );
2518         push( @ivcCylsHigh, unshift @fields );
2519         push( @uMediaType, unshift @fields );
2520         push( @uTracksPerCyl, unshift @fields );
2521         push( @uSectsPerTrack, unshift @fields );
2522         push( @uBytesPerSect, unshift @fields );
2523     }
2524
2525 For the C<$i>th type of supported media, the following variables will
2526 contain the following data.
2527
2528 =over
2529
2530 =item C<$ucCylsLow[$i]>
2531
2532 The low-order 4 bytes of the total number of cylinders.
2533
2534 =item C<$ivcCylsHigh[$i]>
2535
2536 The high-order 4 bytes of the total number of cylinders.
2537
2538 =item C<$uMediaType[$i]>
2539
2540 A code for the type of media.  See the C<":MEDIA_TYPE"> export class.
2541
2542 =item C<$uTracksPerCyl[$i]>
2543
2544 The number of tracks in each cylinder.
2545
2546 =item C<$uSectsPerTrack[$i]>
2547
2548 The number of sectors in each track.
2549
2550 =item C<$uBytesPerSect[$i]>
2551
2552 The number of bytes in each sector.
2553
2554 =back
2555
2556 =back
2557
2558 =item C<":IOCTL_DISK_">
2559
2560 I/O control operations for disk devices.  Used in the C<$uIoControlCode>
2561 argument to C<DeviceIoControl>.  Most of these are to be used on
2562 physical drive devices like C<"//./PhysicalDrive0">.  However,
2563 C<IOCTL_DISK_GET_PARTITION_INFO> and C<IOCTL_DISK_SET_PARTITION_INFO>
2564 should only be used on a single-partition device like C<"//./C:">.  Also,
2565 C<IOCTL_DISK_GET_MEDIA_TYPES> is documented as having been superseded but
2566 is still useful when used on a floppy device like C<"//./A:">.
2567
2568 Includes C<IOCTL_DISK_FORMAT_TRACKS>, C<IOCTL_DISK_FORMAT_TRACKS_EX>,
2569 C<IOCTL_DISK_GET_DRIVE_GEOMETRY>, C<IOCTL_DISK_GET_DRIVE_LAYOUT>,
2570 C<IOCTL_DISK_GET_MEDIA_TYPES>, C<IOCTL_DISK_GET_PARTITION_INFO>,
2571 C<IOCTL_DISK_HISTOGRAM_DATA>, C<IOCTL_DISK_HISTOGRAM_RESET>,
2572 C<IOCTL_DISK_HISTOGRAM_STRUCTURE>, C<IOCTL_DISK_IS_WRITABLE>,
2573 C<IOCTL_DISK_LOGGING>, C<IOCTL_DISK_PERFORMANCE>,
2574 C<IOCTL_DISK_REASSIGN_BLOCKS>, C<IOCTL_DISK_REQUEST_DATA>,
2575 C<IOCTL_DISK_REQUEST_STRUCTURE>, C<IOCTL_DISK_SET_DRIVE_LAYOUT>,
2576 C<IOCTL_DISK_SET_PARTITION_INFO>, and C<IOCTL_DISK_VERIFY>.
2577
2578 =over
2579
2580 =item C<IOCTL_DISK_GET_DRIVE_GEOMETRY>
2581
2582 Request information about the size and geometry of the disk.  C<$pInBuf>
2583 should be C<[]>.  C<$opOutBuf> will be set to a C<DISK_GEOMETRY> data
2584 structure which can be decode via:
2585
2586     ( $ucCylsLow, $ivcCylsHigh, $uMediaType, $uTracksPerCyl,
2587       $uSectsPerTrack, $uBytesPerSect )= unpack( "L l I L L L", $opOutBuf );
2588
2589 =over
2590
2591 =item C<$ucCylsLow>
2592
2593 The low-order 4 bytes of the total number of cylinders.
2594
2595 =item C<$ivcCylsHigh>
2596
2597 The high-order 4 bytes of the total number of cylinders.
2598
2599 =item C<$uMediaType>
2600
2601 A code for the type of media.  See the C<":MEDIA_TYPE"> export class.
2602
2603 =item C<$uTracksPerCyl>
2604
2605 The number of tracks in each cylinder.
2606
2607 =item C<$uSectsPerTrack>
2608
2609 The number of sectors in each track.
2610
2611 =item C<$uBytesPerSect>
2612
2613 The number of bytes in each sector.
2614
2615 =back
2616
2617 =item C<IOCTL_DISK_GET_PARTITION_INFO>
2618
2619 Request information about the size and geometry of the partition.
2620 C<$pInBuf> should be C<[]>.  C<$opOutBuf> will be set to a
2621 C<PARTITION_INFORMATION> data structure which can be decode via:
2622
2623     ( $uStartLow, $ivStartHigh, $ucHiddenSects, $uPartitionSeqNumber,
2624       $uPartitionType, $bActive, $bRecognized, $bToRewrite )=
2625       unpack( "L l L L C c c c", $opOutBuf );
2626
2627 =over
2628
2629 =item C<$uStartLow> and C<$ivStartHigh>
2630
2631 The low-order and high-order [respectively] 4 bytes of the starting
2632 offset of the partition, measured in bytes.
2633
2634 =item C<$ucHiddenSects>
2635
2636 The number of "hidden" sectors for this partition.  Actually this is
2637 the number of sectors found prior to this partition, that is, the
2638 starting offset [as found in C<$uStartLow> and C<$ivStartHigh>]
2639 divided by the number of bytes per sector.
2640
2641 =item C<$uPartitionSeqNumber>
2642
2643 The sequence number of this partition.  Partitions are numbered
2644 starting as C<1> [with "partition 0" meaning the entire disk].
2645 Sometimes this field may be C<0> and you'll have to infer the
2646 partition sequence number from how many partitions precede it on
2647 the disk.
2648
2649 =item C<$uPartitionType>
2650
2651 The type of partition.  See the C<":PARTITION_"> export class for a
2652 list of known types.  See also C<IsRecognizedPartition> and
2653 C<IsContainerPartition>.
2654
2655 =item C<$bActive>
2656
2657 C<1> for the active [boot] partition, C<0> otherwise.
2658
2659 =item C<$bRecognized>
2660
2661 Whether this type of partition is support under Win32.
2662
2663 =item C<$bToRewrite>
2664
2665 Whether to update this partition information.  This field is not used
2666 by C<IOCTL_DISK_GET_PARTITION_INFO>.  For
2667 C<IOCTL_DISK_SET_DRIVE_LAYOUT>, you must set this field to a true
2668 value for any partitions you wish to have changed, added, or deleted.
2669
2670 =back
2671
2672 =item C<IOCTL_DISK_SET_PARTITION_INFO>
2673
2674 Change the type of the partition.  C<$opOutBuf> should be C<[]>.
2675 C<$pInBuf> should be a C<SET_PARTITION_INFORMATION> data structure
2676 which is just a single byte containing the new parition type [see
2677 the C<":PARTITION_"> export class for a list of known types]:
2678
2679     $pInBuf= pack( "C", $uPartitionType );
2680
2681 =item C<IOCTL_DISK_GET_DRIVE_LAYOUT>
2682
2683 Request information about the disk layout.  C<$pInBuf> should be C<[]>.
2684 C<$opOutBuf> will be set to contain C<DRIVE_LAYOUT_INFORMATION>
2685 structure including several C<PARTITION_INFORMATION> structures:
2686
2687     my( $cPartitions, $uDiskSignature )= unpack( "L L", $opOutBuf );
2688     my @fields= unpack( "x8" . ( "L l L L C c c c" x $cPartitions ),
2689                         $opOutBuf );
2690     my( @uStartLow, @ivStartHigh, @ucHiddenSects,
2691       @uPartitionSeqNumber, @uPartitionType, @bActive,
2692       @bRecognized, @bToRewrite )= ();
2693     for(  1..$cPartition  ) {
2694         push( @uStartLow, unshift @fields );
2695         push( @ivStartHigh, unshift @fields );
2696         push( @ucHiddenSects, unshift @fields );
2697         push( @uPartitionSeqNumber, unshift @fields );
2698         push( @uPartitionType, unshift @fields );
2699         push( @bActive, unshift @fields );
2700         push( @bRecognized, unshift @fields );
2701         push( @bToRewrite, unshift @fields );
2702     }
2703
2704 =over
2705
2706 =item C<$cPartitions>
2707
2708 If the number of partitions on the disk.
2709
2710 =item C<$uDiskSignature>
2711
2712 Is the disk signature, a unique number assigned by Disk Administrator
2713 [F<WinDisk.exe>] and used to identify the disk.  This allows drive
2714 letters for partitions on that disk to remain constant even if the
2715 SCSI Target ID of the disk gets changed.
2716
2717 =back
2718
2719 See C<IOCTL_DISK_GET_PARTITION_INFORMATION> for information on the
2720 remaining these fields.
2721
2722 =item C<IOCTL_DISK_GET_MEDIA_TYPES>
2723
2724 Is supposed to be superseded by C<IOCTL_STORAGE_GET_MEDIA_TYPES> but
2725 is still useful for determining the types of floppy diskette formats
2726 that can be produced by a given floppy drive.  See
2727 F<ex/FormatFloppy.plx> for an example.
2728
2729 =item C<IOCTL_DISK_SET_DRIVE_LAYOUT>
2730
2731 Change the partition layout of the disk.  C<$pOutBuf> should be C<[]>.
2732 C<$pInBuf> should be a C<DISK_LAYOUT_INFORMATION> data structure
2733 including several C<PARTITION_INFORMATION> data structures.
2734
2735     # Already set:  $cPartitions, $uDiskSignature, @uStartLow, @ivStartHigh,
2736     #   @ucHiddenSects, @uPartitionSeqNumber, @uPartitionType, @bActive,
2737     #   @bRecognized, and @bToRewrite.
2738     my( @fields, $prtn )= ();
2739     for $prtn (  1..$cPartition  ) {
2740         push( @fields, $uStartLow[$prtn-1], $ivStartHigh[$prtn-1],
2741             $ucHiddenSects[$prtn-1], $uPartitionSeqNumber[$prtn-1],
2742             $uPartitionType[$prtn-1], $bActive[$prtn-1],
2743             $bRecognized[$prtn-1], $bToRewrite[$prtn-1] );
2744     }
2745     $pInBuf= pack( "L L" . ( "L l L L C c c c" x $cPartitions ),
2746                    $cPartitions, $uDiskSignature, @fields );
2747
2748 To delete a partition, zero out all fields except for C<$bToRewrite>
2749 which should be set to C<1>.  To add a partition, increment
2750 C<$cPartitions> and add the information for the new partition
2751 into the arrays, making sure that you insert C<1> into @bToRewrite.
2752
2753 See C<IOCTL_DISK_GET_DRIVE_LAYOUT> and
2754 C<IOCTL_DISK_GET_PARITITON_INFORMATION> for descriptions of the
2755 fields.
2756
2757 =item C<IOCTL_DISK_VERIFY>
2758
2759 Performs a logical format of [part of] the disk.  C<$opOutBuf> should
2760 be C<[]>.  C<$pInBuf> should contain a C<VERIFY_INFORMATION> data
2761 structure:
2762
2763     $pInBuf= pack( "L l L",
2764                    $uStartOffsetLow, $ivStartOffsetHigh, $uLength );
2765
2766 =over
2767
2768 =item C<$uStartOffsetLow> and C<$ivStartOffsetHigh>
2769
2770 The low-order and high-order [respectively] 4 bytes of the offset [in
2771 bytes] where the formatting should begin.
2772
2773 =item C<$uLength>
2774
2775 The length [in bytes] of the section to be formatted.
2776
2777 =back
2778
2779 =item C<IOCTL_DISK_FORMAT_TRACKS>
2780
2781 Format a range of tracks on the disk.  C<$opOutBuf> should be C<[]>.
2782 C<$pInBuf> should contain a C<FORMAT_PARAMETERS> data structure:
2783
2784     $pInBuf= pack( "L L L L L", $uMediaType,
2785                    $uStartCyl, $uEndCyl, $uStartHead, $uEndHead );
2786
2787 C<$uMediaType> if the type of media to be formatted.  Mostly used to
2788 specify the density to use when formatting a floppy diskette.  See the
2789 C<":MEDIA_TYPE"> export class for more information.
2790
2791 The remaining fields specify the starting and ending cylinder and
2792 head of the range of tracks to be formatted.
2793
2794 =item C<IOCTL_DISK_REASSIGN_BLOCKS>
2795
2796 Reassign a list of disk blocks to the disk's spare-block pool.
2797 C<$opOutBuf> should be C<[]>.  C<$pInBuf> should be a
2798 C<REASSIGN_BLOCKS> data structure:
2799
2800     $pInBuf= pack( "S S L*", 0, $cBlocks, @uBlockNumbers );
2801
2802 =item C<IOCTL_DISK_PERFORMANCE>
2803
2804 Request information about disk performance.  C<$pInBuf> should be C<[]>.
2805 C<$opOutBuf> will be set to contain a C<DISK_PERFORMANCE> data structure:
2806
2807     my( $ucBytesReadLow, $ivcBytesReadHigh,
2808         $ucBytesWrittenLow, $ivcBytesWrittenHigh,
2809         $uReadTimeLow, $ivReadTimeHigh,
2810         $uWriteTimeLow, $ivWriteTimeHigh,
2811         $ucReads, $ucWrites, $uQueueDepth )=
2812         unpack( "L l L l L l L l L L L", $opOutBuf );
2813
2814 =item C<IOCTL_DISK_IS_WRITABLE>
2815
2816 No documentation on this IOCTL operation was found.
2817
2818 =item C<IOCTL_DISK_LOGGING>
2819
2820 Control disk logging.  Little documentation for this IOCTL operation
2821 was found.  It makes use of a C<DISK_LOGGING> data structure:
2822
2823 =over
2824
2825 =item DISK_LOGGING_START
2826
2827 Start logging each disk request in a buffer internal to the disk device
2828 driver of size C<$uLogBufferSize>:
2829
2830     $pInBuf= pack( "C L L", 0, 0, $uLogBufferSize );
2831
2832 =item DISK_LOGGING_STOP
2833
2834 Stop loggin each disk request:
2835
2836     $pInBuf= pack( "C L L", 1, 0, 0 );
2837
2838 =item DISK_LOGGING_DUMP
2839
2840 Copy the internal log into the supplied buffer:
2841
2842     $pLogBuffer= ' ' x $uLogBufferSize
2843     $pInBuf= pack( "C P L", 2, $pLogBuffer, $uLogBufferSize );
2844
2845     ( $uByteOffsetLow[$i], $ivByteOffsetHigh[$i],
2846       $uStartTimeLow[$i], $ivStartTimeHigh[$i],
2847       $uEndTimeLog[$i], $ivEndTimeHigh[$i],
2848       $hVirtualAddress[$i], $ucBytes[$i],
2849       $uDeviceNumber[$i], $bWasReading[$i] )=
2850       unpack( "x".(8+8+8+4+4+1+1+2)." L l L l L l L L C c x2", $pLogBuffer );
2851
2852 =item DISK_LOGGING_BINNING
2853
2854 Keep statics grouped into bins based on request sizes.
2855
2856     $pInBuf= pack( "C P L", 3, $pUnknown, $uUnknownSize );
2857
2858 =back
2859
2860 =item C<IOCTL_DISK_FORMAT_TRACKS_EX>
2861
2862 No documentation on this IOCTL is included.
2863
2864 =item C<IOCTL_DISK_HISTOGRAM_STRUCTURE>
2865
2866 No documentation on this IOCTL is included.
2867
2868 =item C<IOCTL_DISK_HISTOGRAM_DATA>
2869
2870 No documentation on this IOCTL is included.
2871
2872 =item C<IOCTL_DISK_HISTOGRAM_RESET>
2873
2874 No documentation on this IOCTL is included.
2875
2876 =item C<IOCTL_DISK_REQUEST_STRUCTURE>
2877
2878 No documentation on this IOCTL operation was found.
2879
2880 =item C<IOCTL_DISK_REQUEST_DATA>
2881
2882 No documentation on this IOCTL operation was found.
2883
2884 =back
2885
2886 =item C<":FSCTL_">
2887
2888 File system control operations.  Used in the C<$uIoControlCode>
2889 argument to C<DeviceIoControl>.
2890
2891 Includes C<FSCTL_SET_REPARSE_POINT>, C<FSCTL_GET_REPARSE_POINT>,
2892 C<FSCTL_DELETE_REPARSE_POINT>.
2893
2894 =over
2895
2896 =item C<FSCTL_SET_REPARSE_POINT>
2897
2898 Sets reparse point data to be associated with $hDevice.
2899
2900 =item C<FSCTL_GET_REPARSE_POINT>
2901
2902 Retrieves the reparse point data associated with $hDevice.
2903
2904 =item C<FSCTL_DELETE_REPARSE_POINT>
2905
2906 Deletes the reparse point data associated with $hDevice.
2907
2908 =back
2909
2910 =item C<":GENERIC_">
2911
2912 Constants specifying generic access permissions that are not specific
2913 to one type of object.
2914
2915         GENERIC_ALL                     GENERIC_EXECUTE
2916         GENERIC_READ            GENERIC_WRITE
2917
2918 =item C<":MEDIA_TYPE">
2919
2920 Different classes of media that a device can support.  Used in the
2921 C<$uMediaType> field of a C<DISK_GEOMETRY> structure.
2922
2923 =over
2924
2925 =item C<Unknown>
2926
2927 Format is unknown.
2928
2929 =item C<F5_1Pt2_512>
2930
2931 5.25" floppy, 1.2MB [really 1,200KB] total space, 512 bytes/sector.
2932
2933 =item C<F3_1Pt44_512>
2934
2935 3.5" floppy, 1.44MB [really 1,440KB] total space, 512 bytes/sector.
2936
2937 =item C<F3_2Pt88_512>
2938
2939 3.5" floppy, 2.88MB [really 2,880KB] total space, 512 bytes/sector.
2940
2941 =item C<F3_20Pt8_512>
2942
2943 3.5" floppy, 20.8MB total space, 512 bytes/sector.
2944
2945 =item C<F3_720_512>
2946
2947 3.5" floppy, 720KB total space, 512 bytes/sector.
2948
2949 =item C<F5_360_512>
2950
2951 5.25" floppy, 360KB total space, 512 bytes/sector.
2952
2953 =item C<F5_320_512>
2954
2955 5.25" floppy, 320KB total space, 512 bytes/sector.
2956
2957 =item C<F5_320_1024>
2958
2959 5.25" floppy, 320KB total space, 1024 bytes/sector.
2960
2961 =item C<F5_180_512>
2962
2963 5.25" floppy, 180KB total space, 512 bytes/sector.
2964
2965 =item C<F5_160_512>
2966
2967 5.25" floppy, 160KB total space, 512 bytes/sector.
2968
2969 =item C<RemovableMedia>
2970
2971 Some type of removable media other than a floppy diskette.
2972
2973 =item C<FixedMedia>
2974
2975 A fixed hard disk.
2976
2977 =item C<F3_120M_512>
2978
2979 3.5" floppy, 120MB total space.
2980
2981 =back
2982
2983 =item C<":MOVEFILE_">
2984
2985 Constants for use in C<$uFlags> arguments to C<MoveFileEx>.
2986
2987         MOVEFILE_COPY_ALLOWED           MOVEFILE_DELAY_UNTIL_REBOOT
2988         MOVEFILE_REPLACE_EXISTING       MOVEFILE_WRITE_THROUGH
2989
2990 =item C<":SECURITY_">
2991
2992 Security quality of service values that can be used in the C<$uFlags>
2993 argument to C<CreateFile> if opening the client side of a named pipe.
2994
2995         SECURITY_ANONYMOUS              SECURITY_CONTEXT_TRACKING
2996         SECURITY_DELEGATION             SECURITY_EFFECTIVE_ONLY
2997         SECURITY_IDENTIFICATION         SECURITY_IMPERSONATION
2998         SECURITY_SQOS_PRESENT
2999
3000 =item C<":SEM_">
3001
3002 Constants to be used with C<SetErrorMode>.
3003
3004         SEM_FAILCRITICALERRORS          SEM_NOGPFAULTERRORBOX
3005         SEM_NOALIGNMENTFAULTEXCEPT      SEM_NOOPENFILEERRORBOX
3006
3007 =item C<":PARTITION_">
3008
3009 Constants describing partition types.
3010
3011         PARTITION_ENTRY_UNUSED          PARTITION_FAT_12
3012         PARTITION_XENIX_1               PARTITION_XENIX_2
3013         PARTITION_FAT_16                PARTITION_EXTENDED
3014         PARTITION_HUGE                  PARTITION_IFS
3015         PARTITION_FAT32                 PARTITION_FAT32_XINT13
3016         PARTITION_XINT13                PARTITION_XINT13_EXTENDED
3017         PARTITION_PREP                  PARTITION_UNIX
3018         VALID_NTFT                      PARTITION_NTFT
3019
3020 =item C<":STD_HANDLE_">
3021
3022 Constants for GetStdHandle and SetStdHandle
3023
3024     STD_ERROR_HANDLE
3025     STD_INPUT_HANDLE
3026     STD_OUTPUT_HANDLE
3027
3028 =item C<":ALL">
3029
3030 All of the above.
3031
3032 =back
3033
3034 =head1 BUGS
3035
3036 None known at this time.
3037
3038 =head1 AUTHOR
3039
3040 Tye McQueen, tye@metronet.com, http://perlmonks.org/?node=tye.
3041
3042 =head1 SEE ALSO
3043
3044 The pyramids.
3045
3046 =cut