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