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