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