Win32API::File(3pm) Perl Programmers Reference Guide Win32API::File(3pm)NAME
Win32API::File - Low-level access to Win32 system API calls for
files/dirs.
SYNOPSIS
use Win32API::File 0.08 qw( :ALL );
MoveFile( $Source, $Destination )
or die "Can't move $Source to $Destination: ",fileLastError(),"\n";
MoveFileEx( $Source, $Destination, MOVEFILE_REPLACE_EXISTING() )
or die "Can't move $Source to $Destination: ",fileLastError(),"\n";
[...]
DESCRIPTION
This provides fairly low-level access to the Win32 System API calls
dealing with files and directories.
To pass in "NULL" as the pointer to an optional buffer, pass in an
empty list reference, "[]".
Beyond raw access to the API calls and related constants, this module
handles smart buffer allocation and translation of return codes.
All functions, unless otherwise noted, return a true value for success
and a false value for failure and set $^E on failure.
Object Oriented/Tied Handle Interface
WARNING: this is new code, use at your own risk.
This version of "Win32API::File" can be used like an "IO::File" object:
my $file = Win32API::File->new("+> foo");
binmode $file;
print $file "hello there\n";
seek $file, 0, 0;
my $line = <$file>;
$file->close;
It also supports tying via a win32 handle (for example, from
"createFile()"):
tie FILE, 'Win32API::File', $win32_handle;
print FILE "...";
It has not been extensively tested yet and buffered I/O is not yet
implemented.
Exports
Nothing is exported by default. The following tags can be used to have
large sets of symbols exported: ":Func", ":FuncA", ":FuncW", ":Misc",
":DDD_", ":DRIVE_", ":FILE_", ":FILE_ATTRIBUTE_", ":FILE_FLAG_",
":FILE_SHARE_", ":FILE_TYPE_", ":FS_", ":FSCTL_", ":HANDLE_FLAG_",
":IOCTL_STORAGE_", ":IOCTL_DISK_", ":GENERIC_", ":MEDIA_TYPE",
":MOVEFILE_", ":SECURITY_", ":SEM_", and ":PARTITION_".
":Func"
The basic function names: "attrLetsToBits", "createFile",
"fileConstant", "fileLastError",
"getLogicalDrives", "setFilePointer", "getFileSize",
"CloseHandle", "CopyFile", "CreateFile",
"DefineDosDevice", "DeleteFile",
"DeviceIoControl", "FdGetOsFHandle", "GetDriveType",
"GetFileAttributes", "GetFileSize", "GetFileType",
"GetHandleInformation", "GetLogicalDrives",
"GetLogicalDriveStrings", "GetOsFHandle", "GetOverlappedResult",
"GetVolumeInformation", "IsContainerPartition",
"IsRecognizedPartition", "MoveFile", "MoveFileEx",
"OsFHandleOpen", "OsFHandleOpenFd",
"QueryDosDevice", "ReadFile", "SetErrorMode",
"SetFilePointer", "SetHandleInformation", and "WriteFile".
attrLetsToBits
"$uBits= attrLetsToBits( $sAttributeLetters )"
Converts a string of file attribute letters into an unsigned
value with the corresponding bits set. $sAttributeLetters
should contain zero or more letters from "achorst":
"a" "FILE_ATTRIBUTE_ARCHIVE"
"c" "FILE_ATTRIBUTE_COMPRESSED"
"h" "FILE_ATTRIBUTE_HIDDEN"
"o" "FILE_ATTRIBUTE_OFFLINE"
"r" "FILE_ATTRIBUTE_READONLY"
"s" "FILE_ATTRIBUTE_SYSTEM"
"t" "FILE_ATTRIBUTE_TEMPORARY"
createFile
"$hObject= createFile( $sPath )"
"$hObject= createFile( $sPath, $rvhvOptions )"
"$hObject= createFile( $sPath, $svAccess )"
"$hObject= createFile( $sPath, $svAccess, $rvhvOptions )"
"$hObject= createFile( $sPath, $svAccess, $svShare )"
"$hObject= createFile( $sPath, $svAccess, $svShare, $rvhvOptions )"
This is a Perl-friendly wrapper around "CreateFile".
On failure, $hObject gets set to a false value and
"regLastError()" and $^E are set to the reason for the failure.
Otherwise, $hObject gets set to a Win32 native file handle
which is alwasy a true value [returns "0 but true" in the
impossible(?) case of the handle having a value of 0].
$sPath is the path to the file [or device, etc.] to be opened.
See "CreateFile" for more information on possible special
values for $sPath.
$svAccess can be a number containing the bit mask representing
the specific type(s) of access to the file that you desire.
See the $uAccess parameter to "CreateFile" for more information
on these values.
More likely, $svAccess is a string describing the generic type
of access you desire and possibly the file creation options to
use. In this case, $svAccess should contain zero or more
characters from "qrw" [access desired], zero or one character
each from "ktn" and "ce", and optional white space. These
letters stand for, respectively, "Query access", "Read access",
"Write access", "Keep if exists", "Truncate if exists", "New
file only", "Create if none", and "Existing file only". Case
is ignored.
You can pass in "?" for $svAccess to have an error message
displayed summarizing its possible values. This is very handy
when doing on-the-fly programming using the Perl debugger:
Win32API::File::createFile: $svAccess can use the following:
One or more of the following:
q -- Query access (same as 0)
r -- Read access (GENERIC_READ)
w -- Write access (GENERIC_WRITE)
At most one of the following:
k -- Keep if exists
t -- Truncate if exists
n -- New file only (fail if file already exists)
At most one of the following:
c -- Create if doesn't exist
e -- Existing file only (fail if doesn't exist)
'' is the same as 'q k e'
'r' is the same as 'r k e'
'w' is the same as 'w t c'
'rw' is the same as 'rw k c'
'rt' or 'rn' implies 'c'.
Or $access can be numeric.
$svAccess is designed to be "do what I mean", so you can skip
the rest of its explanation unless you are interested in the
complex details. Note that, if you want write access to a
device, you need to specify "k" [and perhaps "e", as in "w ke"
or "rw ke"] since Win32 suggests "OPEN_EXISTING" be used when
opening a device.
"q" Stands for "Query access". This is really a no-op since
you always have query access when you open a file. You can
specify "q" to document that you plan to query the file [or
device, etc.]. This is especially helpful when you don't
want read nor write access since something like "q" or "q
ke" may be easier to understand than just "" or "ke".
"r" Stands for "Read access". Sets the "GENERIC_READ" bit(s)
in the $uAccess that is passed to "CreateFile". This is
the default access if the $svAccess parameter is missing
[or if it is "undef" and $rvhvOptions doesn't specify an
"Access" option].
"w" Stands for "Write access". Sets the "GENERIC_WRITE" bit(s)
in the $uAccess that is passed to "CreateFile".
"k" Stands for "Keep if exists". If the requested file exists,
then it is opened. This is the default unless
"GENERIC_WRITE" access has been requested but
"GENERIC_READ" access has not been requested. Contrast
with "t" and "n".
"t" Stands for "Truncate if exists". If the requested file
exists, then it is truncated to zero length and then
opened. This is the default if "GENERIC_WRITE" access has
been requested and "GENERIC_READ" access has not been
requested. Contrast with "k" and "n".
"n" Stands for "New file only". If the requested file exists,
then it is not opened and the "createFile" call fails.
Contrast with "k" and "t". Can't be used with "e".
"c" Stands for "Create if none". If the requested file does
not exist, then it is created and then opened. This is the
default if "GENERIC_WRITE" access has been requested or if
"t" or "n" was specified. Contrast with "e".
"e" Stands for "Existing file only". If the requested file
does not exist, then nothing is opened and the "createFile"
call fails. This is the default unless "GENERIC_WRITE"
access has been requested or "t" or "n" was specified.
Contrast with "c". Can't be used with "n".
The characters from "ktn" and "ce" are combined to determine
the what value for $uCreate to pass to "CreateFile" [unless
overridden by $rvhvOptions]:
"kc"
"OPEN_ALWAYS"
"ke"
"OPEN_EXISTING"
"tc"
"TRUNCATE_EXISTING"
"te"
"CREATE_ALWAYS"
"nc"
"CREATE_NEW"
"ne"
Illegal.
$svShare controls how the file is shared, that is, whether
other processes can have read, write, and/or delete access to
the file while we have it opened. $svShare will usually be a
string containing zero or more characters from "rwd" but can
also be a numeric bit mask.
"r" sets the "FILE_SHARE_READ" bit which allows other processes
to have read access to the file. "w" sets the
"FILE_SHARE_WRITE" bit which allows other processes to have
write access to the file. "d" sets the "FILE_SHARE_DELETE" bit
which allows other processes to have delete access to the file
[ignored under Windows 95].
The default for $svShare is "rw" which provides the same
sharing as using regular perl "open()".
If another process currently has read, write, and/or delete
access to the file and you don't allow that level of sharing,
then your call to "createFile" will fail. If you requested
read, write, and/or delete access and another process already
has the file open but doesn't allow that level of sharing, then
your call to "createFile" will fail. Once you have the file
open, if another process tries to open it with read, write,
and/or delete access and you don't allow that level of sharing,
then that process won't be allowed to open the file.
$rvhvOptions is a reference to a hash where any keys must be
from the list "qw( Access Create Share Attributes Flags
Security Model )". The meaning of the value depends on the key
name, as described below. Any option values in $rvhvOptions
override the settings from $svAccess and $svShare if they
conflict.
Flags => $uFlags
$uFlags is an unsigned value having any of the
"FILE_FLAG_*" or "FILE_ATTRIBUTE_*" bits set. Any
"FILE_ATTRIBUTE_*" bits set via the "Attributes" option are
logically "or"ed with these bits. Defaults to 0.
If opening the client side of a named pipe, then you can
also specify "SECURITY_SQOS_PRESENT" along with one of the
other "SECURITY_*" constants to specify the security
quality of service to be used.
Attributes => $sAttributes
A string of zero or more characters from "achorst" [see
"attrLetsToBits" for more information] which are converted
to "FILE_ATTRIBUTE_*" bits to be set in the $uFlags
argument passed to "CreateFile".
Security => $pSecurityAttributes
$pSecurityAttributes should contain a "SECURITY_ATTRIBUTES"
structure packed into a string or "[]" [the default].
Model => $hModelFile
$hModelFile should contain a handle opened with
"GENERIC_READ" access to a model file from which file
attributes and extended attributes are to be copied. Or
$hModelFile can be 0 [the default].
Access => $sAccess
Access => $uAccess
$sAccess should be a string of zero or more characters from
"qrw" specifying the type of access desired: "query" or 0,
"read" or "GENERIC_READ" [the default], or "write" or
"GENERIC_WRITE".
$uAccess should be an unsigned value containing bits set to
indicate the type of access desired. "GENERIC_READ" is the
default.
Create => $sCreate
Create => $uCreate
$sCreate should be a string constaing zero or one character
from "ktn" and zero or one character from "ce". These
stand for "Keep if exists", "Truncate if exists", "New file
only", "Create if none", and "Existing file only". These
are translated into a $uCreate value.
$uCreate should be one of "OPEN_ALWAYS", "OPEN_EXISTING",
"TRUNCATE_EXISTING", "CREATE_ALWAYS", or "CREATE_NEW".
Share => $sShare
Share => $uShare
$sShare should be a string with zero or more characters
from "rwd" that is translated into a $uShare value. "rw"
is the default.
$uShare should be an unsigned value having zero or more of
the following bits set: "FILE_SHARE_READ",
"FILE_SHARE_WRITE", and "FILE_SHARE_DELETE".
"FILE_SHARE_READ|FILE_SHARE_WRITE" is the default.
Examples:
$hFlop= createFile( "//./A:", "r", "r" )
or die "Can't prevent others from writing to floppy: $^E\n";
$hDisk= createFile( "//./C:", "rw ke", "" )
or die "Can't get exclusive access to C: $^E\n";
$hDisk= createFile( $sFilePath, "ke",
{ Access=>FILE_READ_ATTRIBUTES } )
or die "Can't read attributes of $sFilePath: $^E\n";
$hTemp= createFile( "$ENV{Temp}/temp.$$", "wn", "",
{ Attributes=>"hst", Flags=>FILE_FLAG_DELETE_ON_CLOSE() } )
or die "Can't create temporary file, temp.$$: $^E\n";
getLogicalDrives
"@roots= getLogicalDrives()"
Returns the paths to the root directories of all logical drives
currently defined. This includes all types of drive lettters,
such as floppies, CD-ROMs, hard disks, and network shares. A
typical return value on a poorly equipped computer would be
"("A:\\","C:\\")".
CloseHandle
"CloseHandle( $hObject )"
Closes a Win32 native handle, such as one opened via
"CreateFile". Like most routines, returns a true value if
successful and a false value [and sets $^E and
"regLastError()"] on failure.
CopyFile
"CopyFile( $sOldFileName, $sNewFileName, $bFailIfExists )"
$sOldFileName is the path to the file to be copied.
$sNewFileName is the path to where the file should be copied.
Note that you can NOT just specify a path to a directory in
$sNewFileName to copy the file to that directory using the same
file name.
If $bFailIfExists is true and $sNewFileName is the path to a
file that already exists, then "CopyFile" will fail. If
$bFailIfExists is falsea, then the copy of the $sOldFileNmae
file will overwrite the $sNewFileName file if it already
exists.
Like most routines, returns a true value if successful and a
false value [and sets $^E and "regLastError()"] on failure.
CreateFile
"$hObject= CreateFile( $sPath, $uAccess, $uShare, $pSecAttr,
$uCreate, $uFlags, $hModel )"
On failure, $hObject gets set to a false value and $^E and
"fileLastError()" are set to the reason for the failure.
Otherwise, $hObject gets set to a Win32 native file handle
which is always a true value [returns "0 but true" in the
impossible(?) case of the handle having a value of 0].
$sPath is the path to the file [or device, etc.] to be opened.
$sPath can use "/" or "\\" as path delimiters and can even mix
the two. We will usually only use "/" in our examples since
using "\\" is usually harder to read.
Under Windows NT, $sPath can start with "//?/" to allow the use
of paths longer than "MAX_PATH" [for UNC paths, replace the
leading "//" with "//?/UNC/", as in
"//?/UNC/Server/Share/Dir/File.Ext"].
$sPath can start with "//./" to indicate that the rest of the
path is the name of a "DOS device." You can use
"QueryDosDevice" to list all current DOS devices and can add or
delete them with "DefineDosDevice". If you get the source-code
distribution of this module from CPAN, then it includes an
example script, ex/ListDevs.plx that will list all current DOS
devices and their "native" definition. Again, note that this
doesn't work under Win95 nor Win98.
The most common such DOS devices include:
"//./PhysicalDrive0"
Your entire first hard disk. Doesn't work under Windows
95. This allows you to read or write raw sectors of your
hard disk and to use "DeviceIoControl" to perform
miscellaneous queries and operations to the hard disk.
Writing raw sectors and certain other operations can
seriously damage your files or the function of your
computer.
Locking this for exclusive access [by specifying 0 for
$uShare] doesn't prevent access to the partitions on the
disk nor their file systems. So other processes can still
access any raw sectors within a partition and can use the
file system on the disk as usual.
"//./C:"
Your C: partition. Doesn't work under Windows 95. This
allows you to read or write raw sectors of that partition
and to use "DeviceIoControl" to perform miscellaneous
queries and operations to the partition. Writing raw
sectors and certain other operations can seriously damage
your files or the function of your computer.
Locking this for exclusive access doesn't prevent access to
the physical drive that the partition is on so other
processes can still access the raw sectors that way.
Locking this for exclusive access does prevent other
processes from opening the same raw partition and does
prevent access to the file system on it. It even prevents
the current process from accessing the file system on that
partition.
"//./A:"
The raw floppy disk. Doesn't work under Windows 95. This
allows you to read or write raw sectors of the floppy disk
and to use "DeviceIoControl" to perform miscellaneous
queries and operations to the floopy disk or drive.
Locking this for exclusive access prevents all access to
the floppy.
"//./PIPE/PipeName"
A named pipe, created via "CreateNamedPipe".
$uAccess is an unsigned value with bits set indicating the type
of access desired. Usually either 0 ["query" access],
"GENERIC_READ", "GENERIC_WRITE", "GENERIC_READ|GENERIC_WRITE",
or "GENERIC_ALL". More specific types of access can be
specified, such as "FILE_APPEND_DATA" or "FILE_READ_EA".
$uShare controls how the file is shared, that is, whether other
processes can have read, write, and/or delete access to the
file while we have it opened. $uShare is an unsigned value
with zero or more of these bits set: "FILE_SHARE_READ",
"FILE_SHARE_WRITE", and "FILE_SHARE_DELETE".
If another process currently has read, write, and/or delete
access to the file and you don't allow that level of sharing,
then your call to "CreateFile" will fail. If you requested
read, write, and/or delete access and another process already
has the file open but doesn't allow that level of sharing,
thenn your call to "createFile" will fail. Once you have the
file open, if another process tries to open it with read,
write, and/or delete access and you don't allow that level of
sharing, then that process won't be allowed to open the file.
$pSecAttr should either be "[]" [for "NULL"] or a
"SECURITY_ATTRIBUTES" data structure packed into a string. For
example, if $pSecDesc contains a "SECURITY_DESCRIPTOR"
structure packed into a string, perhaps via:
RegGetKeySecurity( $key, 4, $pSecDesc, 1024 );
then you can set $pSecAttr via:
$pSecAttr= pack( "L P i", 12, $pSecDesc, $bInheritHandle );
$uCreate is one of the following values: "OPEN_ALWAYS",
"OPEN_EXISTING", "TRUNCATE_EXISTING", "CREATE_ALWAYS", and
"CREATE_NEW".
$uFlags is an unsigned value with zero or more bits set
indicating attributes to associate with the file
["FILE_ATTRIBUTE_*" values] or special options ["FILE_FLAG_*"
values].
If opening the client side of a named pipe, then you can also
set $uFlags to include "SECURITY_SQOS_PRESENT" along with one
of the other "SECURITY_*" constants to specify the security
quality of service to be used.
$hModel is 0 [or "[]", both of which mean "NULL"] or a Win32
native handle opened with "GENERIC_READ" access to a model file
from which file attributes and extended attributes are to be
copied if a new file gets created.
Examples:
$hFlop= CreateFile( "//./A:", GENERIC_READ(),
FILE_SHARE_READ(), [], OPEN_EXISTING(), 0, [] )
or die "Can't prevent others from writing to floppy: $^E\n";
$hDisk= CreateFile( $sFilePath, FILE_READ_ATTRIBUTES(),
FILE_SHARE_READ()|FILE_SHARE_WRITE(), [], OPEN_EXISTING(), 0, [] )
or die "Can't read attributes of $sFilePath: $^E\n";
$hTemp= CreateFile( "$ENV{Temp}/temp.$$", GENERIC_WRITE(), 0,
CREATE_NEW(), FILE_FLAG_DELETE_ON_CLOSE()|attrLetsToBits("hst"), [] )
or die "Can't create temporary file, temp.$$: $^E\n";
DefineDosDevice
"DefineDosDevice( $uFlags, $sDosDeviceName, $sTargetPath )"
Defines a new DOS device, overrides the current definition of a
DOS device, or deletes a definition of a DOS device. Like most
routines, returns a true value if successful and a false value
[and sets $^E and "regLastError()"] on failure.
$sDosDeviceName is the name of a DOS device for which we'd like
to add or delete a definition.
$uFlags is an unsigned value with zero or more of the following
bits set:
"DDD_RAW_TARGET_PATH"
Indicates that $sTargetPath will be a raw Windows NT object
name. This usually means that $sTargetPath starts with
"\\Device\\". Note that you cannot use "/" in place of
"\\" in raw target path names.
"DDD_REMOVE_DEFINITION"
Requests that a definition be deleted. If $sTargetPath is
"[]" [for "NULL"], then the most recently added definition
for $sDosDeviceName is removed. Otherwise the most
recently added definition matching $sTargetPath is removed.
If the last definition is removed, then the DOS device name
is also deleted.
"DDD_EXACT_MATCH_ON_REMOVE"
When deleting a definition, this bit causes each
$sTargetPath to be compared to the full-length definition
when searching for the most recently added match. If this
bit is not set, then $sTargetPath only needs to match a
prefix of the definition.
$sTargetPath is the DOS device's specific definition that you
wish to add or delete. For "DDD_RAW_TARGET_PATH", these
usually start with "\\Device\\". If the "DDD_RAW_TARGET_PATH"
bit is not set, then $sTargetPath is just an ordinary path to
some file or directory, providing the functionality of the
subst command.
DeleteFile
"DeleteFile( $sFileName )"
Deletes the named file. Compared to Perl's "unlink",
"DeleteFile" has the advantage of not deleting read-only files.
For some versions of Perl, "unlink" silently calls "chmod"
whether it needs to or not before deleting the file so that
files that you have protected by marking them as read-only are
not always protected from Perl's "unlink".
Like most routines, returns a true value if successful and a
false value [and sets $^E and "regLastError()"] on failure.
DeviceIoControl
"DeviceIoControl( $hDevice, $uIoControlCode, $pInBuf, $lInBuf,
$opOutBuf, $lOutBuf, $olRetBytes, $pOverlapped )"
Requests a special operation on an I/O [input/output] device,
such as ejecting a tape or formatting a disk. Like most
routines, returns a true value if successful and a false value
[and sets $^E and "regLastError()"] on failure.
$hDevice is a Win32 native file handle to a device [return
value from "CreateFile"].
$uIoControlCode is an unsigned value [a "IOCTL_*" or "FSCTL_*"
constant] indicating the type query or other operation to be
performed.
$pInBuf is "[]" [for "NULL"] or a data structure packed into a
string. The type of data structure depends on the
$uIoControlCode value. $lInBuf is 0 or the length of the
structure in $pInBuf. If $pInBuf is not "[]" and $lInBuf is 0,
then $lInBuf will automatically be set to "length($pInBuf)" for
you.
$opOutBuf is "[]" [for "NULL"] or will be set to contain a
returned data structure packed into a string. $lOutBuf
indicates how much space to allocate in $opOutBuf for
"DeviceIoControl" to store the data structure. If $lOutBuf is
a number and $opOutBuf already has a buffer allocated for it
that is larger than $lOutBuf bytes, then this larger buffer
size will be passed to "DeviceIoControl". However, you can
force a specific buffer size to be passed to "DeviceIoControl"
by prepending a "=" to the front of $lOutBuf.
$olRetBytes is "[]" or is a scalar to receive the number of
bytes written to $opOutBuf. Even when $olRetBytes is "[]", a
valid pointer to a "DWORD" [and not "NULL"] is passed to
"DeviceIoControl". In this case, "[]" just means that you
don't care about the value that might be written to
$olRetBytes, which is usually the case since you can usually
use "length($opOutBuf)" instead.
$pOverlapped is "[]" or is a "OVERLAPPED" structure packed into
a string. This is only useful if $hDevice was opened with the
"FILE_FLAG_OVERLAPPED" flag set.
FdGetOsFHandle
"$hNativeHandle= FdGetOsFHandle( $ivFd )"
"FdGetOsFHandle" simply calls "_get_osfhandle()". It was
renamed to better fit in with the rest the function names of
this module, in particular to distinguish it from
"GetOsFHandle". It takes an integer file descriptor [as from
Perl's "fileno"] and returns the Win32 native file handle
associated with that file descriptor or "INVALID_HANDLE_VALUE"
if $ivFd is not an open file descriptor.
When you call Perl's "open" to set a Perl file handle [like
"STDOUT"], Perl calls C's "fopen" to set a stdio "FILE *". C's
"fopen" calls something like Unix's "open", that is, Win32's
"_sopen", to get an integer file descriptor [where 0 is for
"STDIN", 1 for "STDOUT", etc.]. Win32's "_sopen" calls
"CreateFile" to set a "HANDLE", a Win32 native file handle. So
every Perl file handle [like "STDOUT"] has an integer file
descriptor associated with it that you can get via "fileno".
And, under Win32, every file descriptor has a Win32 native file
handle associated with it. "FdGetOsFHandle" lets you get
access to that.
$hNativeHandle is set to "INVALID_HANDLE_VALUE" [and
"lastFileError()" and $^E are set] if "FdGetOsFHandle" fails.
See also "GetOsFHandle" which provides a friendlier interface.
fileConstant
"$value= fileConstant( $sConstantName )"
Fetch the value of a constant. Returns "undef" if
$sConstantName is not the name of a constant supported by this
module. Never sets $! nor $^E.
This function is rarely used since you will usually get the
value of a constant by having that constant imported into your
package by listing the constant name in the "use
Win32API::File" statement and then simply using the constant
name in your code [perhaps followed by "()"]. This function is
useful for verifying constant names not in Perl code, for
example, after prompting a user to type in a constant name.
fileLastError
"$svError= fileLastError();"
"fileLastError( $uError );"
Returns the last error encountered by a routine from this
module. It is just like $^E except it isn't changed by
anything except routines from this module. Ideally you could
just use $^E, but current versions of Perl often overwrite $^E
before you get a chance to check it and really old versions of
Perl don't really support $^E under Win32.
Just like $^E, in a numeric context "fileLastError()" returns
the numeric error value while in a string context it returns a
text description of the error [actually it returns a Perl
scalar that contains both values so "$x= fileLastError()"
causes $x to give different values in string vs. numeric
contexts].
The last form sets the error returned by future calls to
"fileLastError()" and should not be used often. $uError must
be a numeric error code. Also returns the dual-valued version
of $uError.
GetDriveType
"$uDriveType= GetDriveType( $sRootPath )"
Takes a string giving the path to the root directory of a file
system [called a "drive" because every file system is assigned
a "drive letter"] and returns an unsigned value indicating the
type of drive the file system is on. The return value should
be one of:
"DRIVE_UNKNOWN"
None of the following.
"DRIVE_NO_ROOT_DIR"
A "drive" that does not have a file system. This can be a
drive letter that hasn't been defined or a drive letter
assigned to a partition that hasn't been formatted yet.
"DRIVE_REMOVABLE"
A floppy diskette drive or other removable media drive, but
not a CD-ROM drive.
"DRIVE_FIXED"
An ordinary hard disk partition.
"DRIVE_REMOTE"
A network share.
"DRIVE_CDROM"
A CD-ROM drive.
"DRIVE_RAMDISK"
A "ram disk" or memory-resident virtual file system used
for high-speed access to small amounts of temporary file
space.
GetFileAttributes
"$uAttrs = GetFileAttributes( $sPath )"
Takes a path string and returns an unsigned value with
attribute flags. If it fails, it returns
INVALID_FILE_ATTRIBUTES, otherwise it can be one or more of the
following values:
"FILE_ATTRIBUTE_ARCHIVE"
The file or directory is an archive file or directory.
Applications use this attribute to mark files for backup or
removal.
"FILE_ATTRIBUTE_COMPRESSED"
The file or directory is compressed. For a file, this means
that all of the data in the file is compressed. For a
directory, this means that compression is the default for
newly created files and subdirectories.
"FILE_ATTRIBUTE_DEVICE"
Reserved; do not use.
"FILE_ATTRIBUTE_DIRECTORY"
The handle identifies a directory.
"FILE_ATTRIBUTE_ENCRYPTED"
The file or directory is encrypted. For a file, this means
that all data streams in the file are encrypted. For a
directory, this means that encryption is the default for
newly created files and subdirectories.
"FILE_ATTRIBUTE_HIDDEN"
The file or directory is hidden. It is not included in an
ordinary directory listing.
"FILE_ATTRIBUTE_NORMAL"
The file or directory has no other attributes set. This
attribute is valid only if used alone.
"FILE_ATTRIBUTE_NOT_CONTENT_INDEXED"
The file will not be indexed by the content indexing
service.
"FILE_ATTRIBUTE_OFFLINE"
The data of the file is not immediately available. This
attribute indicates that the file data has been physically
moved to offline storage. This attribute is used by Remote
Storage, the hierarchical storage management software.
Applications should not arbitrarily change this attribute.
"FILE_ATTRIBUTE_READONLY"
The file or directory is read-only. Applications can read
the file but cannot write to it or delete it. In the case
of a directory, applications cannot delete it.
"FILE_ATTRIBUTE_REPARSE_POINT"
The file or directory has an associated reparse point.
"FILE_ATTRIBUTE_SPARSE_FILE"
The file is a sparse file.
"FILE_ATTRIBUTE_SYSTEM"
The file or directory is part of, or is used exclusively
by, the operating system.
"FILE_ATTRIBUTE_TEMPORARY"
The file is being used for temporary storage. File systems
avoid writing data back to mass storage if sufficient cache
memory is available, because often the application deletes
the temporary file shortly after the handle is closed. In
that case, the system can entirely avoid writing the data.
Otherwise, the data will be written after the handle is
closed.
GetFileType
"$uFileType= GetFileType( $hFile )"
Takes a Win32 native file handle and returns a "FILE_TYPE_*"
constant indicating the type of the file opened on that handle:
"FILE_TYPE_UNKNOWN"
None of the below. Often a special device.
"FILE_TYPE_DISK"
An ordinary disk file.
"FILE_TYPE_CHAR"
What Unix would call a "character special file", that is, a
device that works on character streams such as a printer
port or a console.
"FILE_TYPE_PIPE"
Either a named or anonymous pipe.
getFileSize
"$size= getFileSize( $hFile )"
This is a Perl-friendly wrapper for the "GetFileSize" (below)
API call.
It takes a Win32 native file handle and returns the size in
bytes. Since the size can be a 64 bit value, on non 64 bit
integer Perls the value returned will be an object of type
"Math::BigInt".
GetFileSize
"$iSizeLow= GetFileSize($win32Handle, $iSizeHigh)"
Returns the size of a file pointed to by $win32Handle,
optionally storing the high order 32 bits into $iSizeHigh if it
is not "[]". If $iSizeHigh is "[]", a non-zero value indicates
success. Otherwise, on failure the return value will be
0xffffffff and "fileLastError()" will not be "NO_ERROR".
GetOverlappedResult
"$bRetval= GetOverlappedResult( $win32Handle, $pOverlapped,
$numBytesTransferred, $bWait )"
Used for asynchronous IO in Win32 to get the result of a
pending IO operation, such as when a file operation returns
"ERROR_IO_PENDING". Returns a false value on failure. The
$overlapped structure and $numBytesTransferred will be modified
with the results of the operation.
As far as creating the $pOverlapped structure, you are
currently on your own.
See
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dllproc/base/getoverlappedresult.asp
<http://msdn.microsoft.com/library/default.asp?url=/library/en-
us/dllproc/base/getoverlappedresult.asp> for more information.
GetLogicalDrives
"$uDriveBits= GetLogicalDrives()"
Returns an unsigned value with one bit set for each drive
letter currently defined. If "A:" is currently a valid drive
letter, then the 1 bit will be set in $uDriveBits. If "B:" is
valid, then the 2 bit will be set. If "Z:" is valid, then the
"2**26" [0x4000000] bit will be set.
GetLogicalDriveStrings
"$olOutLength= GetLogicalDriveStrings( $lBufSize, $osBuffer )"
For each currently defined drive letter, a '\0'-terminated
string of the path to the root of its file system is
constructed. All of these strings are concatenated into a
single larger string and an extra terminating '\0' is added.
This larger string is returned in $osBuffer. Note that this
includes drive letters that have been defined but that have no
file system, such as drive letters assigned to unformatted
partitions.
$lBufSize is the size of the buffer to allocate to store this
list of strings. "26*4+1" is always sufficient and should
usually be used.
$osBuffer is a scalar to be set to contain the constructed
string.
$olOutLength is the number of bytes actually written to
$osBuffer but "length($osBuffer)" can also be used to determine
this.
For example, on a poorly equipped computer,
GetLogicalDriveStrings( 4*26+1, $osBuffer );
might set $osBuffer to the 9-character string,
"A:\\\0C:\\\0\0".
GetHandleInformation
"GetHandleInformation( $hObject, $ouFlags )"
Retrieves the flags associated with a Win32 native file handle
or object handle.
$hObject is an open Win32 native file handle or an open Win32
native handle to some other type of object.
$ouFlags will be set to an unsigned value having zero or more
of the bits "HANDLE_FLAG_INHERIT" and
"HANDLE_FLAG_PROTECT_FROM_CLOSE" set. See the ":HANDLE_FLAG_"
export class for the meanings of these bits.
GetOsFHandle
"$hNativeHandle= GetOsFHandle( FILE )"
Takes a Perl file handle [like "STDIN"] and returns the Win32
native file handle associated with it. See "FdGetOsFHandle"
for more information about Win32 native file handles.
$hNativeHandle is set to a false value [and "lastFileError()"
and $^E are set] if "GetOsFHandle" fails. "GetOsFHandle"
returns "0 but true" in the impossible(?) case of the handle
having a value of 0.
GetVolumeInformation
"GetVolumeInformation( $sRootPath, $osVolName, $lVolName,
$ouSerialNum, $ouMaxNameLen, $ouFsFlags, $osFsType, $lFsType )"
Gets information about a file system volume, returning a true
value if successful. On failure, returns a false value and
sets "fileLastError()" and $^E.
$sRootPath is a string specifying the path to the root of the
file system, for example, "C:/".
$osVolName is a scalar to be set to the string representing the
volume name, also called the file system label. $lVolName is
the number of bytes to allocate for the $osVolName buffer [see
"Buffer Sizes" for more information].
$ouSerialNum is "[]" [for "NULL"] or will be set to the numeric
value of the volume's serial number.
$ouMaxNameLen is "[]" [for "NULL"] or will be set to the
maximum length allowed for a file name or directory name within
the file system.
$osFsType is a scalar to be set to the string representing the
file system type, such as "FAT" or "NTFS". $lFsType is the
number of bytes to allocate for the $osFsType buffer [see
"Buffer Sizes" for more information].
$ouFsFlags is "[]" [for "NULL"] or will be set to an unsigned
integer with bits set indicating properties of the file system:
"FS_CASE_IS_PRESERVED"
The file system preserves the case of file names [usually
true]. That is, it doesn't change the case of file names
such as forcing them to upper- or lower-case.
"FS_CASE_SENSITIVE"
The file system supports the ability to not ignore the case
of file names [but might ignore case the way you are using
it]. That is, the file system has the ability to force you
to get the letter case of a file's name exactly right to be
able to open it. This is true for "NTFS" file systems,
even though case in file names is usually still ignored.
"FS_UNICODE_STORED_ON_DISK"
The file system preserves Unicode in file names [true for
"NTFS"].
"FS_PERSISTENT_ACLS"
The file system supports setting Access Control Lists on
files [true for "NTFS"].
"FS_FILE_COMPRESSION"
The file system supports compression on a per-file basis
[true for "NTFS"].
"FS_VOL_IS_COMPRESSED"
The entire file system is compressed such as via
"DoubleSpace".
IsRecognizedPartition
"IsRecognizedPartition( $ivPartitionType )"
Takes a partition type and returns whether that partition type
is supported under Win32. $ivPartitonType is an integer value
as from the operating system byte of a hard disk's DOS-
compatible partition table [that is, a partition table for
x86-based Win32, not, for example, one used with Windows NT for
Alpha processors]. For example, the "PartitionType" member of
the "PARTITION_INFORMATION" structure.
Common values for $ivPartitionType include
"PARTITION_FAT_12==1", "PARTITION_FAT_16==4",
"PARTITION_EXTENDED==5", "PARTITION_FAT32==0xB".
IsContainerPartition
"IsContainerPartition( $ivPartitionType )"
Takes a partition type and returns whether that partition is a
"container" partition that is supported under Win32, that is,
whether it is an "extended" partition that can contain
"logical" partitions. $ivPartitonType is as for
"IsRecognizedPartition".
MoveFile
"MoveFile( $sOldName, $sNewName )"
Renames a file or directory. $sOldName is the name of the
existing file or directory that is to be renamed. $sNewName is
the new name to give the file or directory. Returns a true
value if the move succeeds. For failure, returns a false value
and sets "fileLastErorr()" and $^E to the reason for the
failure.
Files can be "renamed" between file systems and the file
contents and some attributes will be moved. Directories can
only be renamed within one file system. If there is already a
file or directory named $sNewName, then "MoveFile" will fail.
MoveFileEx
"MoveFileEx( $sOldName, $sNewName, $uFlags )"
Renames a file or directory. $sOldName is the name of the
existing file or directory that is to be renamed. $sNewName is
the new name to give the file or directory. Returns a true
value if the move succeeds. For failure, returns a false value
and sets "fileLastErorr()" and $^E to the reason for the
failure.
$uFlags is an unsigned value with zero or more of the following
bits set:
"MOVEFILE_REPLACE_EXISTING"
If this bit is set and a file [but not a directory] named
$sNewName already exists, then it will be replaced by
$sOldName. If this bit is not set then "MoveFileEx" will
fail rather than replace an existing $sNewName.
"MOVEFILE_COPY_ALLOWED"
Allows files [but not directories] to be moved between file
systems by copying the $sOldName file data and some
attributes to $sNewName and then deleting $sOldName. If
this bit is not set [or if $sOldName denotes a directory]
and $sNewName refers to a different file system than
$sOldName, then "MoveFileEx" will fail.
"MOVEFILE_DELAY_UNTIL_REBOOT"
Preliminary verifications are made and then an entry is
added to the Registry to cause the rename [or delete]
operation to be done the next time this copy of the
operating system is booted [right after any automatic file
system checks have completed]. This is not supported under
Windows 95.
When this bit is set, $sNewName can be "[]" [for "NULL"] to
indicate that $sOldName should be deleted during the next
boot rather than renamed.
Setting both the "MOVEFILE_COPY_ALLOWED" and
"MOVEFILE_DELAY_UNTIL_REBOOT" bits will cause "MoveFileEx"
to fail.
"MOVEFILE_WRITE_THROUGH"
Ensures that "MoveFileEx" won't return until the operation
has finished and been flushed to disk. This is not
supported under Windows 95. Only affects file renames to
another file system, forcing a buffer flush at the end of
the copy operation.
OsFHandleOpen
"OsFHandleOpen( FILE, $hNativeHandle, $sMode )"
Opens a Perl file handle based on an already open Win32 native
file handle [much like C's "fdopen()" does with a file
descriptor]. Returns a true value if the open operation
succeeded. For failure, returns a false value and sets $! [and
possibly "fileLastError()" and $^E] to the reason for the
failure.
"FILE" is a Perl file handle [in any of the supported forms, a
bareword, a string, a typeglob, or a reference to a typeglob]
that will be opened. If "FILE" is already open, it will
automatically be closed before it is reopened.
$hNativeHandle is an open Win32 native file handle, probably
the return value from "CreateFile" or "createFile".
$sMode is string of zero or more letters from "rwatb". These
are translated into a combination "O_RDONLY" ["r"], "O_WRONLY"
["w"], "O_RDWR" ["rw"], "O_APPEND" ["a"], "O_TEXT" ["t"], and
"O_BINARY" ["b"] flags [see the Fcntl module] that is passed to
"OsFHandleOpenFd". Currently only "O_APPEND" and "O_TEXT"
have any significance.
Also, a "r" and/or "w" in $sMode is used to decide how the file
descriptor is converted into a Perl file handle, even though
this doesn't appear to make a difference. One of the following
is used:
open( FILE, "<&=".$ivFd ) # "r" w/o "w"
open( FILE, ">&=".$ivFd ) # "w" w/o "r"
open( FILE, "+<&=".$ivFd ) # both "r" and "w"
"OsFHandleOpen" eventually calls the Win32-specific C routine
"_open_osfhandle()" or Perl's "improved" version called
"win32_open_osfhandle()". Prior to Perl5.005, C's
"_open_osfhandle()" is called which will fail if
"GetFileType($hNativeHandle)" would return "FILE_TYPE_UNKNOWN".
For Perl5.005 and later, "OsFHandleOpen" calls
"win32_open_osfhandle()" from the Perl DLL which doesn't have
this restriction.
OsFHandleOpenFd
"$ivFD= OsFHandleOpenFd( $hNativeHandle, $uMode )"
Opens a file descriptor [$ivFD] based on an already open Win32
native file handle, $hNativeHandle. This just calls the
Win32-specific C routine "_open_osfhandle()" or Perl's
"improved" version called "win32_open_osfhandle()". Prior to
Perl5.005 and in Cygwin Perl, C's "_open_osfhandle()" is called
which will fail if "GetFileType($hNativeHandle)" would return
"FILE_TYPE_UNKNOWN". For Perl5.005 and later,
"OsFHandleOpenFd" calls "win32_open_osfhandle()" from the Perl
DLL which doesn't have this restriction.
$uMode the logical combination of zero or more "O_*" constants
exported by the "Fcntl" module. Currently only "O_APPEND" and
"O_TEXT" have any significance.
$ivFD will be non-negative if the open operation was
successful. For failure, "-1" is returned and $! [and possibly
"fileLastError()" and $^E] is set to the reason for the
failure.
QueryDosDevice
"$olTargetLen= QueryDosDevice( $sDosDeviceName, $osTargetPath,
$lTargetBuf )"
Looks up the definition of a given "DOS" device name, yielding
the active Windows NT native device name along with any
currently dormant definitions.
$sDosDeviceName is the name of the "DOS" device whose
definitions we want. For example, "C:", "COM1", or
"PhysicalDrive0". If $sDosDeviceName is "[]" [for "NULL"], the
list of all DOS device names is returned instead.
$osTargetPath will be assigned a string containing the list of
definitions. The definitions are each '\0'-terminate and are
concatenated into the string, most recent first, with an extra
'\0' at the end of the whole string [see
"GetLogicalDriveStrings" for a sample of this format].
$lTargetBuf is the size [in bytes] of the buffer to allocate
for $osTargetPath. See "Buffer Sizes" for more information.
$olTargetLen is set to the number of bytes written to
$osTargetPath but you can also use "length($osTargetPath)" to
determine this.
For failure, 0 is returned and "fileLastError()" and $^E are
set to the reason for the failure.
ReadFile
"ReadFile( $hFile, $opBuffer, $lBytes, $olBytesRead, $pOverlapped
)"
Reads bytes from a file or file-like device. Returns a true
value if the read operation was successful. For failure,
returns a false value and sets "fileLastError()" and $^E for
the reason for the failure.
$hFile is a Win32 native file handle that is already open to
the file or device to read from.
$opBuffer will be set to a string containing the bytes read.
$lBytes is the number of bytes you would like to read.
$opBuffer is automatically initialized to have a buffer large
enough to hold that many bytes. Unlike other buffer sizes,
$lBytes does not need to have a "=" prepended to it to prevent
a larger value to be passed to the underlying Win32 "ReadFile"
API. However, a leading "=" will be silently ignored, even if
Perl warnings are enabled.
If $olBytesRead is not "[]", it will be set to the actual
number of bytes read, though "length($opBuffer)" can also be
used to determine this.
$pOverlapped is "[]" or is a "OVERLAPPED" structure packed into
a string. This is only useful if $hFile was opened with the
"FILE_FLAG_OVERLAPPED" flag set.
SetErrorMode
"$uOldMode= SetErrorMode( $uNewMode )"
Sets the mode controlling system error handling and returns the
previous mode value. Both $uOldMode and $uNewMode will have
zero or more of the following bits set:
"SEM_FAILCRITICALERRORS"
If set, indicates that when a critical error is
encountered, the call that triggered the error fails
immediately. Normally this bit is not set, which means
that a critical error causes a dialogue box to appear
notifying the desktop user that some application has
triggered a critical error. The dialogue box allows the
desktop user to decide whether the critical error is
returned to the process, is ignored, or the offending
operation is retried.
This affects the "CreateFile" and "GetVolumeInformation"
calls.
Setting this bit is useful for allowing you to check
whether a floppy diskette is in the floppy drive.
"SEM_NOALIGNMENTFAULTEXCEPT"
If set, this causes memory access misalignment faults to be
automatically fixed in a manner invisible to the process.
This flag is ignored on x86-based versions of Windows NT.
This flag is not supported on Windows 95.
"SEM_NOGPFAULTERRORBOX"
If set, general protection faults do not generate a
dialogue box but can instead be handled by the process via
an exception handler. This bit should not be set by
programs that don't know how to handle such faults.
"SEM_NOOPENFILEERRORBOX"
If set, then when an attempt to continue reading from or
writing to an already open file [usually on a removable
medium like a floppy diskette] finds the file no longer
available, the call will immediately fail. Normally this
bit is not set, which means that instead a dialogue box
will appear notifying the desktop user that some
application has run into this problem. The dialogue box
allows the desktop user to decide whether the failure is
returned to the process, is ignored, or the offending
operation is retried.
This affects the "ReadFile" and "WriteFile" calls.
setFilePointer
"$uNewPos = setFilePointer( $hFile, $ivOffset, $uFromWhere )"
This is a perl-friendly wrapper for the SetFilePointer API
(below). $ivOffset can be a 64 bit integer or "Math::BigInt"
object if your Perl doesn't have 64 bit integers. The return
value is the new offset and will likewise be a 64 bit integer
or a "Math::BigInt" object.
SetFilePointer
"$uNewPos = SetFilePointer( $hFile, $ivOffset, $ioivOffsetHigh,
$uFromWhere )"
The native Win32 version of "seek()". "SetFilePointer" sets
the position within a file where the next read or write
operation will start from.
$hFile is a Win32 native file handle.
$uFromWhere is either "FILE_BEGIN", "FILE_CURRENT", or
"FILE_END", indicating that the new file position is being
specified relative to the beginning of the file, the current
file pointer, or the end of the file, respectively.
$ivOffset is [if $ioivOffsetHigh is "[]"] the offset [in bytes]
to the new file position from the position specified via
$uFromWhere. If $ioivOffsetHigh is not "[]", then $ivOffset is
converted to an unsigned value to be used as the low-order 4
bytes of the offset.
$ioivOffsetHigh can be "[]" [for "NULL"] to indicate that you
are only specifying a 4-byte offset and the resulting file
position will be 0xFFFFFFFE or less [just under 4GB].
Otherwise $ioivOfffsetHigh starts out with the high-order 4
bytes [signed] of the offset and gets set to the [unsigned]
high-order 4 bytes of the resulting file position.
The underlying "SetFilePointer" returns 0xFFFFFFFF to indicate
failure, but if $ioivOffsetHigh is not "[]", you would also
have to check $^E to determine whether 0xFFFFFFFF indicates an
error or not. "Win32API::File::SetFilePointer" does this
checking for you and returns a false value if and only if the
underlying "SetFilePointer" failed. For this reason, $uNewPos
is set to "0 but true" if you set the file pointer to the
beginning of the file [or any position with 0 for the low-order
4 bytes].
So the return value will be true if the seek operation was
successful. For failure, a false value is returned and
"fileLastError()" and $^E are set to the reason for the
failure.
SetHandleInformation
"SetHandleInformation( $hObject, $uMask, $uFlags )"
Sets the flags associated with a Win32 native file handle or
object handle. Returns a true value if the operation was
successful. For failure, returns a false value and sets
"fileLastError()" and $^E for the reason for the failure.
$hObject is an open Win32 native file handle or an open Win32
native handle to some other type of object.
$uMask is an unsigned value having one or more of the bits
"HANDLE_FLAG_INHERIT" and "HANDLE_FLAG_PROTECT_FROM_CLOSE" set.
Only bits set in $uMask will be modified by
"SetHandleInformation".
$uFlags is an unsigned value having zero or more of the bits
"HANDLE_FLAG_INHERIT" and "HANDLE_FLAG_PROTECT_FROM_CLOSE" set.
For each bit set in $uMask, the cooresponding bit in the
handle's flags is set to the value of the cooresponding bit in
$uFlags.
If $uOldFlags were the value of the handle's flags before the
call to "SetHandleInformation", then the value of the handle's
flags afterward would be:
( $uOldFlags & ~$uMask ) | ( $uFlags & $uMask )
[at least as far as the "HANDLE_FLAG_INHERIT" and
"HANDLE_FLAG_PROTECT_FROM_CLOSE" bits are concerned.]
See the ":HANDLE_FLAG_" export class for the meanings of these
bits.
WriteFile
"WriteFile( $hFile, $pBuffer, $lBytes, $ouBytesWritten,
$pOverlapped )"
Write bytes to a file or file-like device. Returns a true
value if the operation was successful. For failure, returns a
false value and sets "fileLastError()" and $^E for the reason
for the failure.
$hFile is a Win32 native file handle that is already open to
the file or device to be written to.
$pBuffer is a string containing the bytes to be written.
$lBytes is the number of bytes you would like to write. If
$pBuffer is not at least $lBytes long, "WriteFile" croaks. You
can specify 0 for $lBytes to write "length($pBuffer)" bytes. A
leading "=" on $lBytes will be silently ignored, even if Perl
warnings are enabled.
$ouBytesWritten will be set to the actual number of bytes
written unless you specify it as "[]".
$pOverlapped is "[]" or is an "OVERLAPPED" structure packed
into a string. This is only useful if $hFile was opened with
the "FILE_FLAG_OVERLAPPED" flag set.
":FuncA"
The ASCII-specific functions. Each of these is just the same as
the version without the trailing "A".
CopyFileA
CreateFileA
DefineDosDeviceA
DeleteFileA
GetDriveTypeA
GetFileAttributesA
GetLogicalDriveStringsA
GetVolumeInformationA
MoveFileA
MoveFileExA
QueryDosDeviceA
":FuncW"
The wide-character-specific (Unicode) functions. Each of these is
just the same as the version without the trailing "W" except that
strings are expected in Unicode and some lengths are measured as
number of "WCHAR"s instead of number of bytes, as indicated below.
CopyFileW
"CopyFileW( $swOldFileName, $swNewFileName, $bFailIfExists )"
$swOldFileName and $swNewFileName are Unicode strings.
CreateFileW
"$hObject= CreateFileW( $swPath, $uAccess, $uShare, $pSecAttr,
$uCreate, $uFlags, $hModel )"
$swPath is Unicode.
DefineDosDeviceW
"DefineDosDeviceW( $uFlags, $swDosDeviceName, $swTargetPath )"
$swDosDeviceName and $swTargetPath are Unicode.
DeleteFileW
"DeleteFileW( $swFileName )"
$swFileName is Unicode.
GetDriveTypeW
"$uDriveType= GetDriveTypeW( $swRootPath )"
$swRootPath is Unicode.
GetFileAttributesW
"$uAttrs= GetFileAttributesW( $swPath )"
$swPath is Unicode.
GetLogicalDriveStringsW
"$olwOutLength= GetLogicalDriveStringsW( $lwBufSize, $oswBuffer )"
Unicode is stored in $oswBuffer. $lwBufSize and $olwOutLength
are measured as number of "WCHAR"s.
GetVolumeInformationW
"GetVolumeInformationW( $swRootPath, $oswVolName, $lwVolName,
$ouSerialNum, $ouMaxNameLen, $ouFsFlags, $oswFsType, $lwFsType )"
$swRootPath is Unicode and Unicode is written to $oswVolName
and $oswFsType. $lwVolName and $lwFsType are measures as
number of "WCHAR"s.
MoveFileW
"MoveFileW( $swOldName, $swNewName )"
$swOldName and $swNewName are Unicode.
MoveFileExW
"MoveFileExW( $swOldName, $swNewName, $uFlags )"
$swOldName and $swNewName are Unicode.
QueryDosDeviceW
"$olwTargetLen= QueryDosDeviceW( $swDeviceName, $oswTargetPath,
$lwTargetBuf )"
$swDeviceName is Unicode and Unicode is written to
$oswTargetPath. $lwTargetBuf and $olwTargetLen are measured as
number of "WCHAR"s.
":Misc"
Miscellaneous constants. Used for the $uCreate argument of
"CreateFile" or the $uFromWhere argument of "SetFilePointer". Plus
"INVALID_HANDLE_VALUE", which you usually won't need to check for
since most routines translate it into a false value.
CREATE_ALWAYS CREATE_NEW OPEN_ALWAYS
OPEN_EXISTING TRUNCATE_EXISTING INVALID_HANDLE_VALUE
FILE_BEGIN FILE_CURRENT FILE_END
":DDD_"
Constants for the $uFlags argument of "DefineDosDevice".
DDD_EXACT_MATCH_ON_REMOVE
DDD_RAW_TARGET_PATH
DDD_REMOVE_DEFINITION
":DRIVE_"
Constants returned by "GetDriveType".
DRIVE_UNKNOWN DRIVE_NO_ROOT_DIR DRIVE_REMOVABLE
DRIVE_FIXED DRIVE_REMOTE DRIVE_CDROM
DRIVE_RAMDISK
":FILE_"
Specific types of access to files that can be requested via the
$uAccess argument to "CreateFile".
FILE_READ_DATA FILE_LIST_DIRECTORY
FILE_WRITE_DATA FILE_ADD_FILE
FILE_APPEND_DATA FILE_ADD_SUBDIRECTORY
FILE_CREATE_PIPE_INSTANCE FILE_READ_EA
FILE_WRITE_EA FILE_EXECUTE
FILE_TRAVERSE FILE_DELETE_CHILD
FILE_READ_ATTRIBUTES FILE_WRITE_ATTRIBUTES
FILE_ALL_ACCESS FILE_GENERIC_READ
FILE_GENERIC_WRITE FILE_GENERIC_EXECUTE )],
":FILE_ATTRIBUTE_"
File attribute constants. Returned by "attrLetsToBits" and used in
the $uFlags argument to "CreateFile".
FILE_ATTRIBUTE_ARCHIVE FILE_ATTRIBUTE_COMPRESSED
FILE_ATTRIBUTE_HIDDEN FILE_ATTRIBUTE_NORMAL
FILE_ATTRIBUTE_OFFLINE FILE_ATTRIBUTE_READONLY
FILE_ATTRIBUTE_SYSTEM FILE_ATTRIBUTE_TEMPORARY
In addition, "GetFileAttributes" can return these constants (or
INVALID_FILE_ATTRIBUTES in case of an error).
FILE_ATTRIBUTE_DEVICE FILE_ATTRIBUTE_DIRECTORY
FILE_ATTRIBUTE_ENCRYPTED FILE_ATTRIBUTE_NOT_CONTENT_INDEXED
FILE_ATTRIBUTE_REPARSE_POINT FILE_ATTRIBUTE_SPARSE_FILE
":FILE_FLAG_"
File option flag constants. Used in the $uFlags argument to
"CreateFile".
FILE_FLAG_BACKUP_SEMANTICS FILE_FLAG_DELETE_ON_CLOSE
FILE_FLAG_NO_BUFFERING FILE_FLAG_OVERLAPPED
FILE_FLAG_POSIX_SEMANTICS FILE_FLAG_RANDOM_ACCESS
FILE_FLAG_SEQUENTIAL_SCAN FILE_FLAG_WRITE_THROUGH
FILE_FLAG_OPEN_REPARSE_POINT
":FILE_SHARE_"
File sharing constants. Used in the $uShare argument to
"CreateFile".
FILE_SHARE_DELETE FILE_SHARE_READ FILE_SHARE_WRITE
":FILE_TYPE_"
File type constants. Returned by "GetFileType".
FILE_TYPE_CHAR FILE_TYPE_DISK
FILE_TYPE_PIPE FILE_TYPE_UNKNOWN
":FS_"
File system characteristics constants. Placed in the $ouFsFlags
argument to "GetVolumeInformation".
FS_CASE_IS_PRESERVED FS_CASE_SENSITIVE
FS_UNICODE_STORED_ON_DISK FS_PERSISTENT_ACLS
FS_FILE_COMPRESSION FS_VOL_IS_COMPRESSED
":HANDLE_FLAG_"
Flag bits modifying the behavior of an object handle and accessed
via "GetHandleInformation" and "SetHandleInformation".
HANDLE_FLAG_INHERIT
If this bit is set, then children of this process who inherit
handles [that is, processes created by calls to the Win32
"CreateProcess" API with the "bInheritHandles" parameter
specified as "TRUE"], will inherit this particular object
handle.
HANDLE_FLAG_PROTECT_FROM_CLOSE
If this bit is set, then calls to "CloseHandle" against this
handle will be ignored, leaving the handle open and usable.
":IOCTL_STORAGE_"
I/O control operations for generic storage devices. Used in the
$uIoControlCode argument to "DeviceIoControl". Includes
"IOCTL_STORAGE_CHECK_VERIFY", "IOCTL_STORAGE_MEDIA_REMOVAL",
"IOCTL_STORAGE_EJECT_MEDIA", "IOCTL_STORAGE_LOAD_MEDIA",
"IOCTL_STORAGE_RESERVE", "IOCTL_STORAGE_RELEASE",
"IOCTL_STORAGE_FIND_NEW_DEVICES", and
"IOCTL_STORAGE_GET_MEDIA_TYPES".
"IOCTL_STORAGE_CHECK_VERIFY"
Verify that a device's media is accessible. $pInBuf and
$opOutBuf should both be "[]". If "DeviceIoControl" returns a
true value, then the media is currently accessible.
"IOCTL_STORAGE_MEDIA_REMOVAL"
Allows the device's media to be locked or unlocked. $opOutBuf
should be "[]". $pInBuf should be a "PREVENT_MEDIA_REMOVAL"
data structure, which is simply an interger containing a
boolean value:
$pInBuf= pack( "i", $bPreventMediaRemoval );
"IOCTL_STORAGE_EJECT_MEDIA"
Requests that the device eject the media. $pInBuf and
$opOutBuf should both be "[]".
"IOCTL_STORAGE_LOAD_MEDIA"
Requests that the device load the media. $pInBuf and $opOutBuf
should both be "[]".
"IOCTL_STORAGE_RESERVE"
Requests that the device be reserved. $pInBuf and $opOutBuf
should both be "[]".
"IOCTL_STORAGE_RELEASE"
Releases a previous device reservation. $pInBuf and $opOutBuf
should both be "[]".
"IOCTL_STORAGE_FIND_NEW_DEVICES"
No documentation on this IOCTL operation was found.
"IOCTL_STORAGE_GET_MEDIA_TYPES"
Requests information about the type of media supported by the
device. $pInBuf should be "[]". $opOutBuf will be set to
contain a vector of "DISK_GEOMETRY" data structures, which can
be decoded via:
# Calculate the number of DISK_GEOMETRY structures returned:
my $cStructs= length($opOutBuf)/(4+4+4+4+4+4);
my @fields= unpack( "L l I L L L" x $cStructs, $opOutBuf )
my( @ucCylsLow, @ivcCylsHigh, @uMediaType, @uTracksPerCyl,
@uSectsPerTrack, @uBytesPerSect )= ();
while( @fields ) {
push( @ucCylsLow, unshift @fields );
push( @ivcCylsHigh, unshift @fields );
push( @uMediaType, unshift @fields );
push( @uTracksPerCyl, unshift @fields );
push( @uSectsPerTrack, unshift @fields );
push( @uBytesPerSect, unshift @fields );
}
For the $ith type of supported media, the following variables
will contain the following data.
$ucCylsLow[$i]
The low-order 4 bytes of the total number of cylinders.
$ivcCylsHigh[$i]
The high-order 4 bytes of the total number of cylinders.
$uMediaType[$i]
A code for the type of media. See the ":MEDIA_TYPE" export
class.
$uTracksPerCyl[$i]
The number of tracks in each cylinder.
$uSectsPerTrack[$i]
The number of sectors in each track.
$uBytesPerSect[$i]
The number of bytes in each sector.
":IOCTL_DISK_"
I/O control operations for disk devices. Used in the
$uIoControlCode argument to "DeviceIoControl". Most of these are
to be used on physical drive devices like "//./PhysicalDrive0".
However, "IOCTL_DISK_GET_PARTITION_INFO" and
"IOCTL_DISK_SET_PARTITION_INFO" should only be used on a single-
partition device like "//./C:". Also, "IOCTL_DISK_GET_MEDIA_TYPES"
is documented as having been superceded but is still useful when
used on a floppy device like "//./A:".
Includes "IOCTL_DISK_FORMAT_TRACKS", "IOCTL_DISK_FORMAT_TRACKS_EX",
"IOCTL_DISK_GET_DRIVE_GEOMETRY", "IOCTL_DISK_GET_DRIVE_LAYOUT",
"IOCTL_DISK_GET_MEDIA_TYPES", "IOCTL_DISK_GET_PARTITION_INFO",
"IOCTL_DISK_HISTOGRAM_DATA", "IOCTL_DISK_HISTOGRAM_RESET",
"IOCTL_DISK_HISTOGRAM_STRUCTURE", "IOCTL_DISK_IS_WRITABLE",
"IOCTL_DISK_LOGGING", "IOCTL_DISK_PERFORMANCE",
"IOCTL_DISK_REASSIGN_BLOCKS", "IOCTL_DISK_REQUEST_DATA",
"IOCTL_DISK_REQUEST_STRUCTURE", "IOCTL_DISK_SET_DRIVE_LAYOUT",
"IOCTL_DISK_SET_PARTITION_INFO", and "IOCTL_DISK_VERIFY".
"IOCTL_DISK_GET_DRIVE_GEOMETRY"
Request information about the size and geometry of the disk.
$pInBuf should be "[]". $opOutBuf will be set to a
"DISK_GEOMETRY" data structure which can be decode via:
( $ucCylsLow, $ivcCylsHigh, $uMediaType, $uTracksPerCyl,
$uSectsPerTrack, $uBytesPerSect )= unpack( "L l I L L L", $opOutBuf );
$ucCylsLow
The low-order 4 bytes of the total number of cylinders.
$ivcCylsHigh
The high-order 4 bytes of the total number of cylinders.
$uMediaType
A code for the type of media. See the ":MEDIA_TYPE" export
class.
$uTracksPerCyl
The number of tracks in each cylinder.
$uSectsPerTrack
The number of sectors in each track.
$uBytesPerSect
The number of bytes in each sector.
"IOCTL_DISK_GET_PARTITION_INFO"
Request information about the size and geometry of the
partition. $pInBuf should be "[]". $opOutBuf will be set to a
"PARTITION_INFORMATION" data structure which can be decode via:
( $uStartLow, $ivStartHigh, $ucHiddenSects, $uPartitionSeqNumber,
$uPartitionType, $bActive, $bRecognized, $bToRewrite )=
unpack( "L l L L C c c c", $opOutBuf );
$uStartLow and $ivStartHigh
The low-order and high-order [respectively] 4 bytes of the
starting offset of the partition, measured in bytes.
$ucHiddenSects
The number of "hidden" sectors for this partition.
Actually this is the number of sectors found prior to this
partiton, that is, the starting offset [as found in
$uStartLow and $ivStartHigh] divided by the number of bytes
per sector.
$uPartitionSeqNumber
The sequence number of this partition. Partitions are
numbered starting as 1 [with "partition 0" meaning the
entire disk]. Sometimes this field may be 0 and you'll
have to infer the partition sequence number from how many
partitions preceed it on the disk.
$uPartitionType
The type of partition. See the ":PARTITION_" export class
for a list of known types. See also
"IsRecognizedPartition" and "IsContainerPartition".
$bActive
1 for the active [boot] partition, 0 otherwise.
$bRecognized
Whether this type of partition is support under Win32.
$bToRewrite
Whether to update this partition information. This field
is not used by "IOCTL_DISK_GET_PARTITION_INFO". For
"IOCTL_DISK_SET_DRIVE_LAYOUT", you must set this field to a
true value for any partitions you wish to have changed,
added, or deleted.
"IOCTL_DISK_SET_PARTITION_INFO"
Change the type of the partition. $opOutBuf should be "[]".
$pInBuf should be a "SET_PARTITION_INFORMATION" data structure
which is just a single byte containing the new parition type
[see the ":PARTITION_" export class for a list of known types]:
$pInBuf= pack( "C", $uPartitionType );
"IOCTL_DISK_GET_DRIVE_LAYOUT"
Request information about the disk layout. $pInBuf should be
"[]". $opOutBuf will be set to contain
"DRIVE_LAYOUT_INFORMATION" structure including several
"PARTITION_INFORMATION" structures:
my( $cPartitions, $uDiskSignature )= unpack( "L L", $opOutBuf );
my @fields= unpack( "x8" . ( "L l L L C c c c" x $cPartitions ),
$opOutBuf );
my( @uStartLow, @ivStartHigh, @ucHiddenSects,
@uPartitionSeqNumber, @uPartitionType, @bActive,
@bRecognized, @bToRewrite )= ();
for( 1..$cPartition ) {
push( @uStartLow, unshift @fields );
push( @ivStartHigh, unshift @fields );
push( @ucHiddenSects, unshift @fields );
push( @uPartitionSeqNumber, unshift @fields );
push( @uPartitionType, unshift @fields );
push( @bActive, unshift @fields );
push( @bRecognized, unshift @fields );
push( @bToRewrite, unshift @fields );
}
$cPartitions
If the number of partitions on the disk.
$uDiskSignature
Is the disk signature, a unique number assigned by Disk
Administrator [WinDisk.exe] and used to identify the disk.
This allows drive letters for partitions on that disk to
remain constant even if the SCSI Target ID of the disk gets
changed.
See "IOCTL_DISK_GET_PARTITION_INFORMATION" for information on
the remaining these fields.
"IOCTL_DISK_GET_MEDIA_TYPES"
Is supposed to be superseded by "IOCTL_STORAGE_GET_MEDIA_TYPES"
but is still useful for determining the types of floppy
diskette formats that can be produced by a given floppy drive.
See ex/FormatFloppy.plx for an example.
"IOCTL_DISK_SET_DRIVE_LAYOUT"
Change the partition layout of the disk. $pOutBuf should be
"[]". $pInBuf should be a "DISK_LAYOUT_INFORMATION" data
structure including several "PARTITION_INFORMATION" data
structures.
# Already set: $cPartitions, $uDiskSignature, @uStartLow, @ivStartHigh,
# @ucHiddenSects, @uPartitionSeqNumber, @uPartitionType, @bActive,
# @bRecognized, and @bToRewrite.
my( @fields, $prtn )= ();
for $prtn ( 1..$cPartition ) {
push( @fields, $uStartLow[$prtn-1], $ivStartHigh[$prtn-1],
$ucHiddenSects[$prtn-1], $uPartitionSeqNumber[$prtn-1],
$uPartitionType[$prtn-1], $bActive[$prtn-1],
$bRecognized[$prtn-1], $bToRewrite[$prtn-1] );
}
$pInBuf= pack( "L L" . ( "L l L L C c c c" x $cPartitions ),
$cPartitions, $uDiskSignature, @fields );
To delete a partition, zero out all fields except for
$bToRewrite which should be set to 1. To add a partition,
increment $cPartitions and add the information for the new
partition into the arrays, making sure that you insert 1 into
@bToRewrite.
See "IOCTL_DISK_GET_DRIVE_LAYOUT" and
"IOCTL_DISK_GET_PARITITON_INFORMATION" for descriptions of the
fields.
"IOCTL_DISK_VERIFY"
Performs a logical format of [part of] the disk. $opOutBuf
should be "[]". $pInBuf should contain a "VERIFY_INFORMATION"
data structure:
$pInBuf= pack( "L l L",
$uStartOffsetLow, $ivStartOffsetHigh, $uLength );
$uStartOffsetLow and $ivStartOffsetHigh
The low-order and high-order [respectively] 4 bytes of the
offset [in bytes] where the formatting should begin.
$uLength
The length [in bytes] of the section to be formatted.
"IOCTL_DISK_FORMAT_TRACKS"
Format a range of tracks on the disk. $opOutBuf should be
"[]". $pInBuf should contain a "FORMAT_PARAMETERS" data
structure:
$pInBuf= pack( "L L L L L", $uMediaType,
$uStartCyl, $uEndCyl, $uStartHead, $uEndHead );
$uMediaType if the type of media to be formatted. Mostly used
to specify the density to use when formatting a floppy
diskette. See the ":MEDIA_TYPE" export class for more
information.
The remaining fields specify the starting and ending cylinder
and head of the range of tracks to be formatted.
"IOCTL_DISK_REASSIGN_BLOCKS"
Reassign a list of disk blocks to the disk's spare-block pool.
$opOutBuf should be "[]". $pInBuf should be a
"REASSIGN_BLOCKS" data structure:
$pInBuf= pack( "S S L*", 0, $cBlocks, @uBlockNumbers );
"IOCTL_DISK_PERFORMANCE"
Request information about disk performance. $pInBuf should be
"[]". $opOutBuf will be set to contain a "DISK_PERFORMANCE"
data structure:
my( $ucBytesReadLow, $ivcBytesReadHigh,
$ucBytesWrittenLow, $ivcBytesWrittenHigh,
$uReadTimeLow, $ivReadTimeHigh,
$uWriteTimeLow, $ivWriteTimeHigh,
$ucReads, $ucWrites, $uQueueDepth )=
unpack( "L l L l L l L l L L L", $opOutBuf );
"IOCTL_DISK_IS_WRITABLE"
No documentation on this IOCTL operation was found.
"IOCTL_DISK_LOGGING"
Control disk logging. Little documentation for this IOCTL
operation was found. It makes use of a "DISK_LOGGING" data
structure:
DISK_LOGGING_START
Start logging each disk request in a buffer internal to the
disk device driver of size $uLogBufferSize:
$pInBuf= pack( "C L L", 0, 0, $uLogBufferSize );
DISK_LOGGING_STOP
Stop loggin each disk request:
$pInBuf= pack( "C L L", 1, 0, 0 );
DISK_LOGGING_DUMP
Copy the interal log into the supplied buffer:
$pLogBuffer= ' ' x $uLogBufferSize
$pInBuf= pack( "C P L", 2, $pLogBuffer, $uLogBufferSize );
( $uByteOffsetLow[$i], $ivByteOffsetHigh[$i],
$uStartTimeLow[$i], $ivStartTimeHigh[$i],
$uEndTimeLog[$i], $ivEndTimeHigh[$i],
$hVirtualAddress[$i], $ucBytes[$i],
$uDeviceNumber[$i], $bWasReading[$i] )=
unpack( "x".(8+8+8+4+4+1+1+2)." L l L l L l L L C c x2", $pLogBuffer );
DISK_LOGGING_BINNING
Keep statics grouped into bins based on request sizes.
$pInBuf= pack( "C P L", 3, $pUnknown, $uUnknownSize );
"IOCTL_DISK_FORMAT_TRACKS_EX"
No documentation on this IOCTL is included.
"IOCTL_DISK_HISTOGRAM_STRUCTURE"
No documentation on this IOCTL is included.
"IOCTL_DISK_HISTOGRAM_DATA"
No documentation on this IOCTL is included.
"IOCTL_DISK_HISTOGRAM_RESET"
No documentation on this IOCTL is included.
"IOCTL_DISK_REQUEST_STRUCTURE"
No documentation on this IOCTL operation was found.
"IOCTL_DISK_REQUEST_DATA"
No documentation on this IOCTL operation was found.
":FSCTL_"
File system control operations. Used in the $uIoControlCode
argument to "DeviceIoControl".
Includes "FSCTL_SET_REPARSE_POINT", "FSCTL_GET_REPARSE_POINT",
"FSCTL_DELETE_REPARSE_POINT".
"FSCTL_SET_REPARSE_POINT"
Sets reparse point data to be associated with $hDevice.
"FSCTL_GET_REPARSE_POINT"
Retrieves the reparse point data associated with $hDevice.
"FSCTL_DELETE_REPARSE_POINT"
Deletes the reparse point data associated with $hDevice.
":GENERIC_"
Constants specifying generic access permissions that are not
specific to one type of object.
GENERIC_ALL GENERIC_EXECUTE
GENERIC_READ GENERIC_WRITE
":MEDIA_TYPE"
Different classes of media that a device can support. Used in the
$uMediaType field of a "DISK_GEOMETRY" structure.
"Unknown"
Format is unknown.
"F5_1Pt2_512"
5.25" floppy, 1.2MB [really 1,200KB] total space, 512
bytes/sector.
"F3_1Pt44_512"
3.5" floppy, 1.44MB [really 1,440KB] total space, 512
bytes/sector.
"F3_2Pt88_512"
3.5" floppy, 2.88MB [really 2,880KB] total space, 512
bytes/sector.
"F3_20Pt8_512"
3.5" floppy, 20.8MB total space, 512 bytes/sector.
"F3_720_512"
3.5" floppy, 720KB total space, 512 bytes/sector.
"F5_360_512"
5.25" floppy, 360KB total space, 512 bytes/sector.
"F5_320_512"
5.25" floppy, 320KB total space, 512 bytes/sector.
"F5_320_1024"
5.25" floppy, 320KB total space, 1024 bytes/sector.
"F5_180_512"
5.25" floppy, 180KB total space, 512 bytes/sector.
"F5_160_512"
5.25" floppy, 160KB total space, 512 bytes/sector.
"RemovableMedia"
Some type of removable media other than a floppy diskette.
"FixedMedia"
A fixed hard disk.
"F3_120M_512"
3.5" floppy, 120MB total space.
":MOVEFILE_"
Constants for use in $uFlags arguments to "MoveFileEx".
MOVEFILE_COPY_ALLOWED MOVEFILE_DELAY_UNTIL_REBOOT
MOVEFILE_REPLACE_EXISTING MOVEFILE_WRITE_THROUGH
":SECURITY_"
Security quality of service values that can be used in the $uFlags
argument to "CreateFile" if opening the client side of a named
pipe.
SECURITY_ANONYMOUS SECURITY_CONTEXT_TRACKING
SECURITY_DELEGATION SECURITY_EFFECTIVE_ONLY
SECURITY_IDENTIFICATION SECURITY_IMPERSONATION
SECURITY_SQOS_PRESENT
":SEM_"
Constants to be used with "SetErrorMode".
SEM_FAILCRITICALERRORS SEM_NOGPFAULTERRORBOX
SEM_NOALIGNMENTFAULTEXCEPT SEM_NOOPENFILEERRORBOX
":PARTITION_"
Constants describing partition types.
PARTITION_ENTRY_UNUSED PARTITION_FAT_12
PARTITION_XENIX_1 PARTITION_XENIX_2
PARTITION_FAT_16 PARTITION_EXTENDED
PARTITION_HUGE PARTITION_IFS
PARTITION_FAT32 PARTITION_FAT32_XINT13
PARTITION_XINT13 PARTITION_XINT13_EXTENDED
PARTITION_PREP PARTITION_UNIX
VALID_NTFT PARTITION_NTFT
":ALL"
All of the above.
BUGS
None known at this time.
AUTHOR
Tye McQueen, tye@metronet.com, http://www.metronet.com/~tye/.
SEE ALSO
The pyramids.
perl v5.14.2 2011-09-26 Win32API::File(3pm)
