| Win32API::File - Low-level access to Win32 system API calls for files/dirs. |
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"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 )$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
$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 )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""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"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"GENERIC_WRITE bit(s) in the
$uAccess that is passed to CreateFile.
"k"GENERIC_WRITE access has been
requested but GENERIC_READ access has not been requested. Contrast
with "t" and "n".
"t"GENERIC_WRITE access has been requested and GENERIC_READ access
has not been requested. Contrast with "k" and "n".
"n"createFile call fails. Contrast with "k" and
"t". Can't be used with "e".
"c"GENERIC_WRITE access has been requested or if "t" or
"n" was specified. Contrast with "e".
"e"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"$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 ored 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.
"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()("A:\\","C:\\").
CloseHandle( $hObject )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.
$hObject= CreateFile( $sPath, $uAccess, $uShare, $pSecAttr, $uCreate, $uFlags, $hModel )$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"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:"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:"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"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 )$^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$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$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$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 )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 )$^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 )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 );$^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 )DRIVE_UNKNOWNDRIVE_NO_ROOT_DIRDRIVE_REMOVABLEDRIVE_FIXEDDRIVE_REMOTEDRIVE_CDROMDRIVE_RAMDISK$uAttrs = GetFileAttributes( $sPath )FILE_ATTRIBUTE_ARCHIVEFILE_ATTRIBUTE_COMPRESSEDFILE_ATTRIBUTE_DEVICEFILE_ATTRIBUTE_DIRECTORYFILE_ATTRIBUTE_ENCRYPTEDFILE_ATTRIBUTE_HIDDENFILE_ATTRIBUTE_NORMALFILE_ATTRIBUTE_NOT_CONTENT_INDEXEDFILE_ATTRIBUTE_OFFLINEFILE_ATTRIBUTE_READONLYFILE_ATTRIBUTE_REPARSE_POINTFILE_ATTRIBUTE_SPARSE_FILEFILE_ATTRIBUTE_SYSTEMFILE_ATTRIBUTE_TEMPORARY$uFileType= GetFileType( $hFile )FILE_TYPE_* constant
indicating the type of the file opened on that handle:
FILE_TYPE_UNKNOWNFILE_TYPE_DISKFILE_TYPE_CHARFILE_TYPE_PIPE$size= getFileSize( $hFile )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)$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 )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 for more information.
$uDriveBits= GetLogicalDrives()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 )'\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 )$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 )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 )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_PRESERVEDFS_CASE_SENSITIVEFS_UNICODE_STORED_ON_DISKFS_PERSISTENT_ACLSFS_FILE_COMPRESSIONFS_VOL_IS_COMPRESSEDIsRecognizedPartition( $ivPartitionType )$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 )$ivPartitonType is as for IsRecognizedPartition.
MoveFile( $sOldName, $sNewName )$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 )$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$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$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_REBOOTWhen 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_THROUGHMoveFileEx 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 )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 the Fcntl manpage 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 )$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 )$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 )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 )$uOldMode and $uNewMode will have
zero or more of the following bits set:
SEM_FAILCRITICALERRORSThis 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_NOALIGNMENTFAULTEXCEPTSEM_NOGPFAULTERRORBOXSEM_NOOPENFILEERRORBOX$uNewPos = setFilePointer( $hFile, $ivOffset, $uFromWhere )$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 )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 )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 )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"
CopyFileA
CreateFileA
DefineDosDeviceA
DeleteFileA
GetDriveTypeA
GetFileAttributesA
GetLogicalDriveStringsA
GetVolumeInformationA
MoveFileA
MoveFileExA
QueryDosDeviceA
":FuncW"WCHARs instead of number of bytes, as indicated below.
CopyFileW( $swOldFileName, $swNewFileName, $bFailIfExists )$swOldFileName and $swNewFileName are Unicode strings.
$hObject= CreateFileW( $swPath, $uAccess, $uShare, $pSecAttr, $uCreate, $uFlags, $hModel )$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 )$oswBuffer. $lwBufSize and $olwOutLength
are measured as number of WCHARs.
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 WCHARs.
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 WCHARs.
":Misc"$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_"$uFlags argument of DefineDosDevice.
DDD_EXACT_MATCH_ON_REMOVE
DDD_RAW_TARGET_PATH
DDD_REMOVE_DEFINITION
":DRIVE_"GetDriveType.
DRIVE_UNKNOWN DRIVE_NO_ROOT_DIR DRIVE_REMOVABLE
DRIVE_FIXED DRIVE_REMOTE DRIVE_CDROM
DRIVE_RAMDISK
":FILE_"$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_"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_"$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_"$uShare argument to
CreateFile.
FILE_SHARE_DELETE FILE_SHARE_READ FILE_SHARE_WRITE
":FILE_TYPE_"GetFileType.
FILE_TYPE_CHAR FILE_TYPE_DISK
FILE_TYPE_PIPE FILE_TYPE_UNKNOWN
":FS_"$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_"GetHandleInformation and SetHandleInformation.
CreateProcess API
with the bInheritHandles parameter specified as TRUE], will inherit
this particular object handle.
CloseHandle against this handle
will be ignored, leaving the handle open and usable.
":IOCTL_STORAGE_"$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$pInBuf and $opOutBuf
should both be []. If DeviceIoControl returns a true value, then
the media is currently accessible.
IOCTL_STORAGE_MEDIA_REMOVAL$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$pInBuf and $opOutBuf
should both be [].
IOCTL_STORAGE_LOAD_MEDIA$pInBuf and $opOutBuf
should both be [].
IOCTL_STORAGE_RESERVE$pInBuf and $opOutBuf
should both be [].
IOCTL_STORAGE_RELEASE$pInBuf and $opOutBuf
should both be [].
IOCTL_STORAGE_FIND_NEW_DEVICESIOCTL_STORAGE_GET_MEDIA_TYPES$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]$ivcCylsHigh[$i]$uMediaType[$i]":MEDIA_TYPE" export class.
$uTracksPerCyl[$i]$uSectsPerTrack[$i]$uBytesPerSect[$i]":IOCTL_DISK_"$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$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$ivcCylsHigh$uMediaType":MEDIA_TYPE" export class.
$uTracksPerCyl$uSectsPerTrack$uBytesPerSectIOCTL_DISK_GET_PARTITION_INFO$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$ucHiddenSects$uStartLow and $ivStartHigh]
divided by the number of bytes per sector.
$uPartitionSeqNumber1 [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":PARTITION_" export class for a
list of known types. See also IsRecognizedPartition and
IsContainerPartition.
$bActive1 for the active [boot] partition, 0 otherwise.
$bRecognized$bToRewriteIOCTL_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$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$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$uDiskSignatureSee IOCTL_DISK_GET_PARTITION_INFORMATION for information on the
remaining these fields.
IOCTL_DISK_GET_MEDIA_TYPESIOCTL_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$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$opOutBuf should
be []. $pInBuf should contain a VERIFY_INFORMATION data
structure:
$pInBuf= pack( "L l L",
$uStartOffsetLow, $ivStartOffsetHigh, $uLength );
$uStartOffsetLow and $ivStartOffsetHigh$uLengthIOCTL_DISK_FORMAT_TRACKS$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$opOutBuf should be []. $pInBuf should be a
REASSIGN_BLOCKS data structure:
$pInBuf= pack( "S S L*", 0, $cBlocks, @uBlockNumbers );
IOCTL_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_WRITABLEIOCTL_DISK_LOGGINGDISK_LOGGING data structure:
$uLogBufferSize:
$pInBuf= pack( "C L L", 0, 0, $uLogBufferSize );
$pInBuf= pack( "C L L", 1, 0, 0 );
$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 );
$pInBuf= pack( "C P L", 3, $pUnknown, $uUnknownSize );
IOCTL_DISK_FORMAT_TRACKS_EXIOCTL_DISK_HISTOGRAM_STRUCTUREIOCTL_DISK_HISTOGRAM_DATAIOCTL_DISK_HISTOGRAM_RESETIOCTL_DISK_REQUEST_STRUCTUREIOCTL_DISK_REQUEST_DATA":FSCTL_"$uIoControlCode
argument to DeviceIoControl.
Includes FSCTL_SET_REPARSE_POINT, FSCTL_GET_REPARSE_POINT,
FSCTL_DELETE_REPARSE_POINT.
FSCTL_SET_REPARSE_POINTFSCTL_GET_REPARSE_POINTFSCTL_DELETE_REPARSE_POINT":GENERIC_"
GENERIC_ALL GENERIC_EXECUTE
GENERIC_READ GENERIC_WRITE
":MEDIA_TYPE"$uMediaType field of a DISK_GEOMETRY structure.
UnknownF5_1Pt2_512F3_1Pt44_512F3_2Pt88_512F3_20Pt8_512F3_720_512F5_360_512F5_320_512F5_320_1024F5_180_512F5_160_512RemovableMediaFixedMediaF3_120M_512":MOVEFILE_"$uFlags arguments to MoveFileEx.
MOVEFILE_COPY_ALLOWED MOVEFILE_DELAY_UNTIL_REBOOT
MOVEFILE_REPLACE_EXISTING MOVEFILE_WRITE_THROUGH
":SECURITY_"$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_"SetErrorMode.
SEM_FAILCRITICALERRORS SEM_NOGPFAULTERRORBOX
SEM_NOALIGNMENTFAULTEXCEPT SEM_NOOPENFILEERRORBOX
":PARTITION_"
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_"
STD_ERROR_HANDLE
STD_INPUT_HANDLE
STD_OUTPUT_HANDLE
":ALL"
None known at this time.
Tye McQueen, tye@metronet.com, http://perlmonks.org/?node=tye.
The pyramids.
| Win32API::File - Low-level access to Win32 system API calls for files/dirs. |