cpan/Win32API-File/File.pm

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