tools/cmake/scripts/IPC/Win32APIFile.pm

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