Win32API::File - Low-level access to Win32 system API calls for files/dirs.

MoveFile( $Source, $Destination ) or die "Can't move $Source to $Destination: ",fileLastError(),"\n"; MoveFileEx( $Source, $Destination, MOVEFILE_REPLACE_EXISTING() ) or die "Can't move $Source to $Destination: ",fileLastError(),"\n"; [...]

DESCRIPTION

This provides fairly low-level access to the Win32 System API calls dealing with files and directories.

To pass in NULL as the pointer to an optional buffer, pass in an empty list reference, [].

Beyond raw access to the API calls and related constants, this module handles smart buffer allocation and translation of return codes.

All functions, unless otherwise noted, return a true value for success and a false value for failure and set $^E on failure.

Exports

":Func"

The basic function names: attrLetsToBits, createFile, fileConstant, fileLastError, getLogicalDrives, CloseHandle, CopyFile, CreateFile, DefineDosDevice, DeleteFile, DeviceIoControl, FdGetOsFHandle, GetDriveType, GetFileType, GetHandleInformation, GetLogicalDrives, GetLogicalDriveStrings, GetOsFHandle, GetVolumeInformation, IsRecognizedPartition, IsContainerPartition, MoveFile, MoveFileEx, OsFHandleOpen, OsFHandleOpenFd, QueryDosDevice, ReadFile, SetErrorMode, SetFilePointer, SetHandleInformation, and WriteFile.

attrLetsToBits

$uBits= attrLetsToBits( $sAttributeLetters )

Converts a string of file attribute letters into an unsigned value with the corresponding bits set. $sAttributeLetters should contain zero or more letters from "achorst":

"a": FILE_ATTRIBUTE_ARCHIVE
"c": FILE_ATTRIBUTE_COMPRESSED
"h": FILE_ATTRIBUTE_HIDDEN
"o": FILE_ATTRIBUTE_OFFLINE
"r": FILE_ATTRIBUTE_READONLY
"s": FILE_ATTRIBUTE_SYSTEM
"t": FILE_ATTRIBUTE_TEMPORARY

createFile

$hObject= createFile( $sPath )

$hObject= createFile( $sPath, $rvhvOptions )

$hObject= createFile( $sPath, $svAccess )

$hObject= createFile( $sPath, $svAccess, $rvhvOptions )

$hObject= createFile( $sPath, $svAccess, $svShare )

$hObject= createFile( $sPath, $svAccess, $svShare, $rvhvOptions )

This is a Perl-friendly wrapper around CreateFile.

On failure, $hObject gets set to a false value and regLastError() and $^E are set to the reason for the failure. Otherwise, $hObject gets set to a Win32 native file handle which is alwasy a true value [returns "0 but true" in the impossible(?) case of the handle having a value of 0].

$sPath is the path to the file [or device, etc.] to be opened. See CreateFile for more information on possible special values for $sPath.

$svAccess can be a number containing the bit mask representing the specific type(s) of access to the file that you desire. See the $uAccess parameter to CreateFile for more information on these values.

More likely, $svAccess is a string describing the generic type of access you desire and possibly the file creation options to use. In this case, $svAccess should contain zero or more characters from "qrw" [access desired], zero or one character each from "ktn" and "ce", and optional white space. These letters stand for, respectively, ``Query access'', ``Read access'', ``Write access'', ``Keep if exists'', ``Truncate if exists'', ``New file only'', ``Create if none'', and ``Existing file only''. Case is ignored.

You can pass in "?" for $svAccess to have an error message displayed summarizing its possible values. This is very handy when doing on-the-fly programming using the Perl debugger:

    Win32API::File::createFile:  $svAccess can use the following:
        One or more of the following:
            q -- Query access (same as 0)
            r -- Read access (GENERIC_READ)
            w -- Write access (GENERIC_WRITE)
        At most one of the following:
            k -- Keep if exists
            t -- Truncate if exists
            n -- New file only (fail if file already exists)
        At most one of the following:
            c -- Create if doesn't exist
            e -- Existing file only (fail if doesn't exist)
      ''   is the same as 'q  k e'
      'r'  is the same as 'r  k e'
      'w'  is the same as 'w  t c'
      'rw' is the same as 'rw k c'
      'rt' or 'rn' implies 'c'.
      Or $access can be numeric.

$svAccess is designed to be ``do what I mean'', so you can skip the rest of its explanation unless you are interested in the complex details. Note that, if you want write access to a device, you need to specify "k" [and perhaps "e", as in "w ke" or "rw ke"] since Win32 suggests OPEN_EXISTING be used when opening a device.

"q": Stands for ``Query access''. This is really a no-op since you always have query access when you open a file. You can specify "q" to document that you plan to query the file [or device, etc.]. This is especially helpful when you don't want read nor write access since something like "q" or "q ke" may be easier to understand than just "" or "ke".
"r": Stands for ``Read access''. Sets the GENERIC_READ bit(s) in the $uAccess that is passed to CreateFile. This is the default access if the $svAccess parameter is missing [or if it is undef and $rvhvOptions doesn't specify an "Access" option].
"w": Stands for ``Write access''. Sets the GENERIC_WRITE bit(s) in the $uAccess that is passed to CreateFile.
"k": Stands for ``Keep if exists''. If the requested file exists, then it is opened. This is the default unless GENERIC_WRITE access has been requested but GENERIC_READ access has not been requested. Contrast with "t" and "n".
"t": Stands for ``Truncate if exists''. If the requested file exists, then it is truncated to zero length and then opened. This is the default if GENERIC_WRITE access has been requested and GENERIC_READ access has not been requested. Contrast with "k" and "n".
"n": Stands for ``New file only''. If the requested file exists, then it is not opened and the createFile call fails. Contrast with "k" and "t". Can't be used with "e".
"c": Stands for ``Create if none''. If the requested file does not exist, then it is created and then opened. This is the default if GENERIC_WRITE access has been requested or if "t" or "n" was specified. Contrast with "e".
"e": Stands for ``Existing file only''. If the requested file does not exist, then nothing is opened and the createFile call fails. This is the default unless GENERIC_WRITE access has been requested or "t" or "n" was specified. Contrast with "c". Can't be used with "n".

The characters from "ktn" and "ce" are combined to determine the what value for $uCreate to pass to CreateFile [unless overridden by $rvhvOptions]:

"kc": OPEN_ALWAYS
"ke": OPEN_EXISTING
"tc": TRUNCATE_EXISTING
"te": CREATE_ALWAYS
"nc": CREATE_NEW
"ne": Illegal.

$svShare controls how the file is shared, that is, whether other processes can have read, write, and/or delete access to the file while we have it opened. $svShare will usually be a string containing zero or more characters from "rwd" but can also be a numeric bit mask.

"r" sets the FILE_SHARE_READ bit which allows other processes to have read access to the file. "w" sets the FILE_SHARE_WRITE bit which allows other processes to have write access to the file. "d" sets the FILE_SHARE_DELETE bit which allows other processes to have delete access to the file [ignored under Windows 95].

The default for $svShare is "rw" which provides the same sharing as using regular perl open().

If another process currently has read, write, and/or delete access to the file and you don't allow that level of sharing, then your call to createFile will fail. If you requested read, write, and/or delete access and another process already has the file open but doesn't allow that level of sharing, then your call to createFile will fail. Once you have the file open, if another process tries to open it with read, write, and/or delete access and you don't allow that level of sharing, then that process won't be allowed to open the file.

$rvhvOptions is a reference to a hash where any keys must be from the list qw( Access Create Share Attributes Flags Security Model ). The meaning of the value depends on the key name, as described below. Any option values in $rvhvOptions override the settings from $svAccess and $svShare if they conflict.

Flags => $uFlags

$uFlags is an unsigned value having any of the FILE_FLAG_* or FILE_ATTRIBUTE_* bits set. Any FILE_ATTRIBUTE_* bits set via the Attributes option are logically 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.

Attributes => $sAttributes

A string of zero or more characters from "achorst" [see attrLetsToBits for more information] which are converted to FILE_ATTRIBUTE_* bits to be set in the $uFlags argument passed to CreateFile.

Security => $pSecurityAttributes

$pSecurityAttributes should contain a SECURITY_ATTRIBUTES structure packed into a string or [] [the default].

Model => $hModelFile

$hModelFile should contain a handle opened with GENERIC_READ access to a model file from which file attributes and extended attributes are to be copied. Or $hModelFile can be 0 [the default].

Access => $sAccess

Access => $uAccess

$sAccess should be a string of zero or more characters from "qrw" specifying the type of access desired: ``query'' or 0, ``read'' or GENERIC_READ [the default], or ``write'' or GENERIC_WRITE.

$uAccess should be an unsigned value containing bits set to indicate the type of access desired. GENERIC_READ is the default.

Create => $sCreate

Create => $uCreate

$sCreate should be a string constaing zero or one character from "ktn" and zero or one character from "ce". These stand for ``Keep if exists'', ``Truncate if exists'', ``New file only'', ``Create if none'', and ``Existing file only''. These are translated into a $uCreate value.

$uCreate should be one of OPEN_ALWAYS, OPEN_EXISTING, TRUNCATE_EXISTING, CREATE_ALWAYS, or CREATE_NEW.

Share => $sShare

Share => $uShare

$sShare should be a string with zero or more characters from "rwd" that is translated into a $uShare value. "rw" is the default.

$uShare should be an unsigned value having zero or more of the following bits set: FILE_SHARE_READ, FILE_SHARE_WRITE, and FILE_SHARE_DELETE. FILE_SHARE_READ|FILE_SHARE_WRITE is the default.

Examples:

    $hFlop= createFile( "//./A:", "r", "r" )
      or  die "Can't prevent others from writing to floppy: $^E\n";
    $hDisk= createFile( "//./C:", "rw ke", "" )
      or  die "Can't get exclusive access to C: $^E\n";
    $hDisk= createFile( $sFilePath, "ke",
      { Access=>FILE_READ_ATTRIBUTES } )
      or  die "Can't read attributes of $sFilePath: $^E\n";
    $hTemp= createFile( "$ENV{Temp}/temp.$$", "wn", "",
      { Attributes=>"hst", Flags=>FILE_FLAG_DELETE_ON_CLOSE() } )
      or  die "Can't create temporary file, temp.$$: $^E\n";

getLogicalDrives

@roots= getLogicalDrives()

Returns the paths to the root directories of all logical drives currently defined. This includes all types of drive lettters, such as floppies, CD-ROMs, hard disks, and network shares. A typical return value on a poorly equipped computer would be ("A:\\","C:\\").

CloseHandle

CloseHandle( $hObject )

Closes a Win32 native handle, such as one opened via CreateFile. Like most routines, returns a true value if successful and a false value [and sets $^E and regLastError()] on failure.

CopyFile

CopyFile( $sOldFileName, $sNewFileName, $bFailIfExists )

$sOldFileName is the path to the file to be copied. $sNewFileName is the path to where the file should be copied. Note that you can &NOT; just specify a path to a directory in $sNewFileName to copy the file to that directory using the same file name.

If $bFailIfExists is true and $sNewFileName is the path to a file that already exists, then CopyFile will fail. If $bFailIfExists is falsea, then the copy of the $sOldFileNmae file will overwrite the $sNewFileName file if it already exists.

Like most routines, returns a true value if successful and a false value [and sets $^E and regLastError()] on failure.

CreateFile

$hObject= CreateFile( $sPath, $uAccess, $uShare, $pSecAttr, $uCreate, $uFlags, $hModel )

On failure, $hObject gets set to a false value and $^E and fileLastError() are set to the reason for the failure. Otherwise, $hObject gets set to a Win32 native file handle which is always a true value [returns "0 but true" in the impossible(?) case of the handle having a value of 0].

$sPath is the path to the file [or device, etc.] to be opened.

$sPath can use "/" or "\\" as path delimiters and can even mix the two. We will usually only use "/" in our examples since using "\\" is usually harder to read.

Under Windows NT, $sPath can start with "//?/" to allow the use of paths longer than MAX_PATH [for UNC paths, replace the leading "//" with "//?/UNC/", as in "//?/UNC/Server/Share/Dir/File.Ext"].

$sPath can start with "//./" to indicate that the rest of the path is the name of a ``DOS device.'' You can use QueryDosDevice to list all current DOS devices and can add or delete them with DefineDosDevice. If you get the source-code distribution of this module from CPAN, then it includes an example script, ex/ListDevs.plx that will list all current DOS devices and their ``native'' definition. Again, note that this doesn't work under Win95 nor Win98.

The most common such DOS devices include:

"//./PhysicalDrive0"

Your entire first hard disk. Doesn't work under Windows 95. This allows you to read or write raw sectors of your hard disk and to use DeviceIoControl to perform miscellaneous queries and operations to the hard disk. Writing raw sectors and certain other operations can seriously damage your files or the function of your computer.

Locking this for exclusive access [by specifying 0 for $uShare] doesn't prevent access to the partitions on the disk nor their file systems. So other processes can still access any raw sectors within a partition and can use the file system on the disk as usual.

"//./C:"

Your C: partition. Doesn't work under Windows 95. This allows you to read or write raw sectors of that partition and to use DeviceIoControl to perform miscellaneous queries and operations to the partition. Writing raw sectors and certain other operations can seriously damage your files or the function of your computer.

Locking this for exclusive access doesn't prevent access to the physical drive that the partition is on so other processes can still access the raw sectors that way. Locking this for exclusive access &does; prevent other processes from opening the same raw partition and &does; prevent access to the file system on it. It even prevents the current process from accessing the file system on that partition.

"//./A:"

The raw floppy disk. Doesn't work under Windows 95. This allows you to read or write raw sectors of the floppy disk and to use DeviceIoControl to perform miscellaneous queries and operations to the floopy disk or drive.

Locking this for exclusive access prevents all access to the floppy.

"//./PIPE/PipeName"

A named pipe, created via CreateNamedPipe.

$uAccess is an unsigned value with bits set indicating the type of access desired. Usually either 0 [``query'' access], GENERIC_READ, GENERIC_WRITE, GENERIC_READ|GENERIC_WRITE, or GENERIC_ALL. More specific types of access can be specified, such as FILE_APPEND_DATA or FILE_READ_EA.

$uShare controls how the file is shared, that is, whether other processes can have read, write, and/or delete access to the file while we have it opened. $uShare is an unsigned value with zero or more of these bits set: FILE_SHARE_READ, FILE_SHARE_WRITE, and FILE_SHARE_DELETE.

If another process currently has read, write, and/or delete access to the file and you don't allow that level of sharing, then your call to CreateFile will fail. If you requested read, write, and/or delete access and another process already has the file open but doesn't allow that level of sharing, thenn your call to createFile will fail. Once you have the file open, if another process tries to open it with read, write, and/or delete access and you don't allow that level of sharing, then that process won't be allowed to open the file.

$pSecAttr should either be [] [for NULL] or a SECURITY_ATTRIBUTES data structure packed into a string. For example, if $pSecDesc contains a SECURITY_DESCRIPTOR structure packed into a string, perhaps via:

    RegGetKeySecurity( $key, 4, $pSecDesc, 1024 );

then you can set $pSecAttr via:

    $pSecAttr= pack( "L P i", 12, $pSecDesc, $bInheritHandle );

$uCreate is one of the following values: OPEN_ALWAYS, OPEN_EXISTING, TRUNCATE_EXISTING, CREATE_ALWAYS, and CREATE_NEW.

$uFlags is an unsigned value with zero or more bits set indicating attributes to associate with the file [FILE_ATTRIBUTE_* values] or special options [FILE_FLAG_* values].

If opening the client side of a named pipe, then you can also set $uFlags to include SECURITY_SQOS_PRESENT along with one of the other SECURITY_* constants to specify the security quality of service to be used.

$hModel is 0 [or [], both of which mean NULL] or a Win32 native handle opened with GENERIC_READ access to a model file from which file attributes and extended attributes are to be copied if a new file gets created.

Examples:

    $hFlop= CreateFile( "//./A:", GENERIC_READ(),
      FILE_SHARE_READ(), [], OPEN_EXISTING(), 0, [] )
      or  die "Can't prevent others from writing to floppy: $^E\n";
    $hDisk= createFile( $sFilePath, FILE_READ_ATTRIBUTES(),
      FILE_SHARE_READ()|FILE_SHARE_WRITE(), [], OPEN_EXISTING(), 0, [] )
      or  die "Can't read attributes of $sFilePath: $^E\n";
    $hTemp= createFile( "$ENV{Temp}/temp.$$", GENERIC_WRITE(), 0,
      CREATE_NEW(), FILE_FLAG_DELETE_ON_CLOSE()|attrLetsToBits("hst"), [] )
      or  die "Can't create temporary file, temp.$$: $^E\n";

DefineDosDevice

DefineDosDevice( $uFlags, $sDosDeviceName, $sTargetPath )

Defines a new DOS device, overrides the current definition of a DOS device, or deletes a definition of a DOS device. Like most routines, returns a true value if successful and a false value [and sets $^E and regLastError()] on failure.

$sDosDeviceName is the name of a DOS device for which we'd like to add or delete a definition.

$uFlags is an unsigned value with zero or more of the following bits set:

DDD_RAW_TARGET_PATH

Indicates that $sTargetPath will be a raw Windows NT object name. This usually means that $sTargetPath starts with "\\Device\\". Note that you cannot use "/" in place of "\\" in raw target path names.

DDD_REMOVE_DEFINITION

Requests that a definition be deleted. If $sTargetPath is [] [for NULL], then the most recently added definition for $sDosDeviceName is removed. Otherwise the most recently added definition matching $sTargetPath is removed.

If the last definition is removed, then the DOS device name is also deleted.

DDD_EXACT_MATCH_ON_REMOVE

When deleting a definition, this bit causes each $sTargetPath to be compared to the full-length definition when searching for the most recently added match. If this bit is not set, then $sTargetPath only needs to match a prefix of the definition.

$sTargetPath is the DOS device's specific definition that you wish to add or delete. For DDD_RAW_TARGET_PATH, these usually start with "\\Device\\". If the DDD_RAW_TARGET_PATH bit is not set, then $sTargetPath is just an ordinary path to some file or directory, providing the functionality of the subst command.

DeleteFile

DeleteFile( $sFileName )

Deletes the named file. Compared to Perl's unlink, DeleteFile has the advantage of not deleting read-only files. For &some; versions of Perl, unlink silently calls chmod whether it needs to or not before deleting the file so that files that you have protected by marking them as read-only are not always protected from Perl's unlink.

Like most routines, returns a true value if successful and a false value [and sets $^E and regLastError()] on failure.

DeviceIoControl

DeviceIoControl( $hDevice, $uIoControlCode, $pInBuf, $lInBuf, $opOutBuf, $lOutBuf, $olRetBytes, $pOverlapped )

Requests a special operation on an I/O [input/output] device, such as ejecting a tape or formatting a disk. Like most routines, returns a true value if successful and a false value [and sets $^E and regLastError()] on failure.

$hDevice is a Win32 native file handle to a device [return value from CreateFile].

$uIoControlCode is an unsigned value [a IOCTL_* constant] indicating the type query or other operation to be performed.

$pInBuf is [] [for NULL] or a data structure packed into a string. The type of data structure depends on the $uIoControlCode value. $lInBuf is 0 or the length of the structure in $pInBuf. If $pInBuf is not [] and $lInBuf is 0, then $lInBuf will automatically be set to length($pInBuf) for you.

$opOutBuf is [] [for NULL] or will be set to contain a returned data structure packed into a string. $lOutBuf indicates how much space to allocate in $opOutBuf for DeviceIoControl to store the data structure. If $lOutBuf is a number and $opOutBuf already has a buffer allocated for it that is larger than $lOutBuf bytes, then this larger buffer size will be passed to DeviceIoControl. However, you can force a specific buffer size to be passed to DeviceIoControl by prepending a "=" to the front of $lOutBuf.

$olRetBytes is [] or is a scalar to receive the number of bytes written to $opOutBuf. Even when $olRetBytes is [], a valid pointer to a DWORD [and not NULL] is passed to DeviceIoControl. In this case, [] just means that you don't care about the value that might be written to $olRetBytes, which is usually the case since you can usually use length($opOutBuf) instead.

$pOverlapped is [] or is a OVERLAPPED structure packed into a string. This is only useful if $hDevice was opened with the FILE_FLAG_OVERLAPPED flag set.

FdGetOsFHandle

$hNativeHandle= FdGetOsFHandle( $ivFd )

FdGetOsFHandle simply calls _get_osfhandle(). It was renamed to better fit in with the rest the function names of this module, in particular to distinguish it from GetOsFHandle. It takes an integer file descriptor [as from Perl's fileno] and returns the Win32 native file handle associated with that file descriptor or INVALID_HANDLE_VALUE if $ivFd is not an open file descriptor.

When you call Perl's open to set a Perl file handle [like STDOUT], Perl calls C's fopen to set a stdio FILE *. C's fopen calls something like Unix's open, that is, Win32's _sopen, to get an integer file descriptor [where 0 is for STDIN, 1 for STDOUT, etc.]. Win32's _sopen calls CreateFile to set a HANDLE, a Win32 native file handle. So every Perl file handle [like STDOUT] has an integer file descriptor associated with it that you can get via fileno. And, under Win32, every file descriptor has a Win32 native file handle associated with it. FdGetOsFHandle lets you get access to that.

$hNativeHandle is set to INVALID_HANDLE_VALUE [and lastFileError() and $^E are set] if FdGetOsFHandle fails. See also GetOsFHandle which provides a friendlier interface.

fileConstant

$value= fileConstant( $sConstantName )

Fetch the value of a constant. Returns undef if $sConstantName is not the name of a constant supported by this module. Never sets $! nor $^E.

This function is rarely used since you will usually get the value of a constant by having that constant imported into your package by listing the constant name in the use Win32API::File statement and then simply using the constant name in your code [perhaps followed by ()]. This function is useful for verifying constant names not in Perl code, for example, after prompting a user to type in a constant name.

fileLastError

$svError= fileLastError();

fileLastError( $uError );

Returns the last error encountered by a routine from this module. It is just like $^E except it isn't changed by anything except routines from this module. Ideally you could just use $^E, but current versions of Perl often overwrite $^E before you get a chance to check it and really old versions of Perl don't really support $^E under Win32.

Just like $^E, in a numeric context fileLastError() returns the numeric error value while in a string context it returns a text description of the error [actually it returns a Perl scalar that contains both values so $x= fileLastError() causes $x to give different values in string vs. numeric contexts]. On old versions of Perl where $^E isn't tied to GetLastError(), fileLastError simply returns the number of the error and you'll need to use <Win32::FormatMessage> to get the error string.

The last form sets the error returned by future calls to fileLastError() and should not be used often. $uError must be a numeric error code. Also returns the dual-valued version of $uError.

GetDriveType

$uDriveType= GetDriveType( $sRootPath )

Takes a string giving the path to the root directory of a file system [called a ``drive'' because every file system is assigned a ``drive letter''] and returns an unsigned value indicating the type of drive the file system is on. The return value should be one of:

DRIVE_UNKNOWN: None of the following.
DRIVE_NO_ROOT_DIR: A ``drive'' that does not have a file system. This can be a drive letter that hasn't been defined or a drive letter assigned to a partition that hasn't been formatted yet.
DRIVE_REMOVABLE: A floppy diskette drive or other removable media drive, but not a CD-ROM drive.
DRIVE_FIXED: An ordinary hard disk partition.
DRIVE_REMOTE: A network share.
DRIVE_CDROM: A CD-ROM drive.
DRIVE_RAMDISK: A ``ram disk'' or memory-resident virtual file system used for high-speed access to small amounts of temporary file space.

GetFileType

$uFileType= GetFileType( $hFile )

Takes a Win32 native file handle and returns a FILE_TYPE_* constant indicating the type of the file opened on that handle:

FILE_TYPE_UNKNOWN: None of the below. Often a special device.
FILE_TYPE_DISK: An ordinary disk file.
FILE_TYPE_CHAR: What Unix would call a ``character special file'', that is, a device that works on character streams such as a printer port or a console.
FILE_TYPE_PIPE: Either a named or anonymous pipe.

GetLogicalDrives

$uDriveBits= GetLogicalDrives()

Returns an unsigned value with one bit set for each drive letter currently defined. If ``A:'' is currently a valid drive letter, then the 1 bit will be set in $uDriveBits. If ``B:'' is valid, then the 2 bit will be set. If ``Z:'' is valid, then the 2**26 [0x4000000] bit will be set.

GetLogicalDriveStrings

$olOutLength= GetLogicalDriveStrings( $lBufSize, $osBuffer )

For each currently defined drive letter, a '\0'-terminated string of the path to the root of its file system is constructed. All of these strings are concatenated into a single larger string and an extra terminating '\0' is added. This larger string is returned in $osBuffer. Note that this includes drive letters that have been defined but that have no file system, such as drive letters assigned to unformatted partitions.

$lBufSize is the size of the buffer to allocate to store this list of strings. 26*4+1 is always sufficient and should usually be used.

$osBuffer is a scalar to be set to contain the constructed string.

$olOutLength is the number of bytes actually written to $osBuffer but length($osBuffer) can also be used to determine this.

For example, on a poorly equipped computer,

    GetLogicalDriveStrings( 4*26+1, $osBuffer );

might set $osBuffer to the 9-character string, "A:\\\0C:\\\0\0".

GetHandleInformation

GetHandleInformation( $hObject, $ouFlags )

Retrieves the flags associated with a Win32 native file handle or object handle.

$hObject is an open Win32 native file handle or an open Win32 native handle to some other type of object.

$ouFlags will be set to an unsigned value having zero or more of the bits HANDLE_FLAG_INHERIT and HANDLE_FLAG_PROTECT_FROM_CLOSE set. See the ":HANDLE_FLAG_" export class for the meanings of these bits.

GetOsFHandle

$hNativeHandle= GetOsFHandle( FILE )

Takes a Perl file handle [like STDIN] and returns the Win32 native file handle associated with it. See FdGetOsFHandle for more information about Win32 native file handles.

$hNativeHandle is set to a false value [and lastFileError() and $^E are set] if GetOsFHandle fails. GetOsFHandle returns "0 but true" in the impossible(?) case of the handle having a value of 0.

GetVolumeInformation

GetVolumeInformation( $sRootPath, $osVolName, $lVolName, $ouSerialNum, $ouMaxNameLen, $ouFsFlags, $osFsType, $lFsType )

Gets information about a file system volume, returning a true value if successful. On failure, returns a false value and sets fileLastError() and $^E.

$sRootPath is a string specifying the path to the root of the file system, for example, "C:/".

$osVolName is a scalar to be set to the string representing the volume name, also called the file system label. $lVolName is the number of bytes to allocate for the $osVolName buffer [see Buffer Sizes for more information].

$ouSerialNum is [] [for NULL] or will be set to the numeric value of the volume's serial number.

$ouMaxNameLen is [] [for NULL] or will be set to the maximum length allowed for a file name or directory name within the file system.

$osFsType is a scalar to be set to the string representing the file system type, such as "FAT" or "NTFS". $lFsType is the number of bytes to allocate for the $osFsType buffer [see Buffer Sizes for more information].

$ouFsFlags is [] [for NULL] or will be set to an unsigned integer with bits set indicating properties of the file system:

FS_CASE_IS_PRESERVED: The file system preserves the case of file names [usually true]. That is, it doesn't change the case of file names such as forcing them to upper- or lower-case.
FS_CASE_SENSITIVE: The file system supports the ability to not ignore the case of file names [but might ignore case the way you are using it]. That is, the file system has the ability to force you to get the letter case of a file's name exactly right to be able to open it. This is true for ``NTFS'' file systems, even though case in file names is usually still ignored.
FS_UNICODE_STORED_ON_DISK: The file system preserves Unicode in file names [true for ``NTFS''].
FS_PERSISTENT_ACLS: The file system supports setting Access Control Lists on files [true for ``NTFS''].
FS_FILE_COMPRESSION: The file system supports compression on a per-file basis [true for ``NTFS''].
FS_VOL_IS_COMPRESSED: The entire file system is compressed such as via ``DoubleSpace''.

IsRecognizedPartition

IsRecognizedPartition( $ivPartitionType )

Takes a partition type and returns whether that partition type is supported under Win32. $ivPartitonType is an integer value as from the operating system byte of a hard disk's DOS-compatible partition table [that is, a partition table for x86-based Win32, not, for example, one used with Windows NT for Alpha processors]. For example, the PartitionType member of the PARTITION_INFORMATION structure.

Common values for $ivPartitionType include PARTITION_FAT_12==1, PARTITION_FAT_16==4, PARTITION_EXTENDED==5, PARTITION_FAT32==0xB.

IsContainerPartition

IsContainerPartition( $ivPartitionType )

Takes a partition type and returns whether that partition is a ``container'' partition that is supported under Win32, that is, whether it is an ``extended'' partition that can contain ``logical'' partitions. $ivPartitonType is as for IsRecognizedPartition.

MoveFile

MoveFile( $sOldName, $sNewName )

Renames a file or directory. $sOldName is the name of the existing file or directory that is to be renamed. $sNewName is the new name to give the file or directory. Returns a true value if the move succeeds. For failure, returns a false value and sets fileLastErorr() and $^E to the reason for the failure.

Files can be ``renamed'' between file systems and the file contents and some attributes will be moved. Directories can only be renamed within one file system. If there is already a file or directory named $sNewName, then MoveFile will fail.

MoveFileEx

MoveFileEx( $sOldName, $sNewName, $uFlags )

$uFlags is an unsigned value with zero or more of the following bits set:

MOVEFILE_REPLACE_EXISTING

If this bit is set and a file [but not a directory] named $sNewName already exists, then it will be replaced by $sOldName. If this bit is not set then MoveFileEx will fail rather than replace an existing $sNewName.

MOVEFILE_COPY_ALLOWED

Allows files [but not directories] to be moved between file systems by copying the $sOldName file data and some attributes to $sNewName and then deleting $sOldName. If this bit is not set [or if $sOldName denotes a directory] and $sNewName refers to a different file system than $sOldName, then MoveFileEx will fail.

MOVEFILE_DELAY_UNTIL_REBOOT

Preliminary verifications are made and then an entry is added to the Registry to cause the rename [or delete] operation to be done the next time this copy of the operating system is booted [right after any automatic file system checks have completed]. This is not supported under Windows 95.

When this bit is set, $sNewName can be [] [for NULL] to indicate that $sOldName should be deleted during the next boot rather than renamed.

Setting both the MOVEFILE_COPY_ALLOWED and MOVEFILE_DELAY_UNTIL_REBOOT bits will cause MoveFileEx to fail.

MOVEFILE_WRITE_THROUGH

Ensures that MoveFileEx won't return until the operation has finished and been flushed to disk. This is not supported under Windows 95. Only affects file renames to another file system, forcing a buffer flush at the end of the copy operation.

OsFHandleOpen

OsFHandleOpen( FILE, $hNativeHandle, $sMode )

Opens a Perl file handle based on an already open Win32 native file handle [much like C's fdopen() does with a file descriptor]. Returns a true value if the open operation succeeded. For failure, returns a false value and sets $! [and possibly fileLastError() and $^E] to the reason for the failure.

FILE is a Perl file handle [in any of the supported forms, a bareword, a string, a typeglob, or a reference to a typeglob] that will be opened. If FILE is already open, it will automatically be closed before it is reopened.

$hNativeHandle is an open Win32 native file handle, probably the return value from CreateFile or createFile.

$sMode is string of zero or more letters from "rwatb". These are translated into a combination O_RDONLY ["r"], O_WRONLY ["w"], O_RDWR ["rw"], O_APPEND ["a"], O_TEXT ["t"], and O_BINARY ["b"] flags [see the 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.

OsFHandleOpenFd

$ivFD= OsFHandleOpenFd( $hNativeHandle, $uMode )

Opens a file descriptor [$ivFD] based on an already open Win32 native file handle, $hNativeHandle. This just calls the Win32-specific C routine _open_osfhandle() or Perl's ``improved'' version called win32_open_osfhandle(). Prior to Perl5.005, C's _open_osfhandle() is called which will fail if GetFileType($hNativeHandle) would return FILE_TYPE_UNKNOWN. For Perl5.005 and later, OsFHandleOpenFd calls win32_open_osfhandle() from the Perl DLL which doesn't have this restriction.

$uMode the logical combination of zero or more O_* constants exported by the Fcntl module. Currently only O_APPEND and O_TEXT have any significance.

$ivFD will be non-negative if the open operation was successful. For failure, -1 is returned and $! [and possibly fileLastError() and $^E] is set to the reason for the failure.

QueryDosDevice

$olTargetLen= QueryDosDevice( $sDosDeviceName, $osTargetPath, $lTargetBuf )

Looks up the definition of a given ``DOS'' device name, yielding the active Windows NT native device name along with any currently dormant definitions.

$sDosDeviceName is the name of the ``DOS'' device whose definitions we want. For example, "C:", "COM1

ActivePerl Documentation
Table of Contents

Core Perl Documentation

Pragmas

Libraries

NAME

SUPPORTED PLATFORMS

SYNOPSIS

DESCRIPTION

Exports

ActivePerl DocumentationTable of Contents

Core Perl Documentation

Pragmas

Libraries

NAME

SUPPORTED PLATFORMS

SYNOPSIS

DESCRIPTION

Exports

ActivePerl Documentation
Table of Contents