Win32API::File - Low-level access to Win32 system API calls for files/dirs.
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";
[...]
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.
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.
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
.
$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"
:
$hObject= createFile( $sPath )
$hObject= createFile( $sPath, $rvhvOptions )
$hObject= createFile( $sPath, $svAccess )
$hObject= createFile( $sPath, $svAccess, $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 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. 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.
$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.
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
.
$pSecurityAttributes
should contain a SECURITY_ATTRIBUTES
structure packed into a string or []
[the default].
$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].
$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.
$sCreate
should be a string containing 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
.
$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";
@roots= getLogicalDrives()
Returns the paths to the root directories of all logical drives currently defined. This includes all types of drive letters, such as floppies, CD-ROMs, hard disks, and network shares. A typical return value on a poorly equipped computer would be ("A:\\","C:\\")
.
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( $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 false, 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.
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 floppy 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, 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.
$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( $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( $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( $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.
$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.
$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.
$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
.
$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.
$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.
$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.
$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
.
$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
.
$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 for more information.
$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.
$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( $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.
$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( $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( $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( $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( $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( $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( 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.
$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.
$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( $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.
$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.
$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.
$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( $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 corresponding bit in the handle's flags is set to the value of the corresponding 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( $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( $swOldFileName, $swNewFileName, $bFailIfExists )
$swOldFileName
and $swNewFileName
are Unicode strings.
$swPath
is Unicode.
DefineDosDeviceW( $uFlags, $swDosDeviceName, $swTargetPath )
$swDosDeviceName
and $swTargetPath
are Unicode.
DeleteFileW( $swFileName )
$swFileName
is Unicode.
$uDriveType= GetDriveTypeW( $swRootPath )
$swRootPath
is Unicode.
$uAttrs= GetFileAttributesW( $swPath )
$swPath
is Unicode.
$olwOutLength= GetLogicalDriveStringsW( $lwBufSize, $oswBuffer )
Unicode is stored in $oswBuffer
. $lwBufSize
and $olwOutLength
are measured as number of WCHAR
s.
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( $swOldName, $swNewName )
$swOldName
and $swNewName
are Unicode.
MoveFileExW( $swOldName, $swNewName, $uFlags )
$swOldName
and $swNewName
are Unicode.
$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
.
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.
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 integer 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 $i
th 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 superseded 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 partition, 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 precede 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 partition 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 );
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:
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 );
Stop logging each disk request:
$pInBuf= pack( "C L L", 1, 0, 0 );
Copy the internal 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 );
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
.
":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
":STD_HANDLE_"
Constants for GetStdHandle and SetStdHandle
STD_ERROR_HANDLE
STD_INPUT_HANDLE
STD_OUTPUT_HANDLE
":ALL"
All of the above.
None known at this time.
Tye McQueen, tye@metronet.com, http://perlmonks.org/?node=tye.
The pyramids.