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

- NAME
- SYNOPSIS
- DESCRIPTION

- Exports

- BUGS
- AUTHOR
- SEE ALSO

# NAME

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

# SYNOPSIS

      use Win32API::File 0.08 qw( :ALL );

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

# DESCRIPTION

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

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

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

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

## Exports

Nothing is exported by default. The following tags can be used to have large sets of symbols exported: `":Func"`, `":FuncA"`, `":FuncW"`, `":Misc"`, `":DDD_"`, `":DRIVE_"`, `":FILE_"`, `":FILE_ATTRIBUTE_"`, `":FILE_FLAG_"`, `":FILE_SHARE_"`, `":FILE_TYPE_"`, `":FS_"`, `":HANDLE_FLAG_"`, `":IOCTL_STORAGE_"`, `":IOCTL_DISK_"`, `":GENERIC_"`, `":MEDIA_TYPE"`, `":MOVEFILE_"`, `":SECURITY_"`, `":SEM_"`, and `":PARTITION_"`.

`":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 `or`ed with these bits. Defaults to `0`.

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

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

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

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

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

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

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

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

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

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

    Examples:

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

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

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

  CopyFile
  `CopyFile( $sOldFileName, $sNewFileName, $bFailIfExists )`
    `$sOldFileName` is the path to the file to be copied. `$sNewFileName` is the path to where the file should be copied. Note that you can NOT just specify a path to a directory in `$sNewFileName` to copy the file to that directory using the same file name.

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

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

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

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

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

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

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

    The most common such DOS devices include:

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

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

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

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

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

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

    `"//./PIPE/PipeName"`
      A named pipe, created via `CreateNamedPipe`.

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

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

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

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

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

    then you can set `$pSecAttr` via:

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

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

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

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

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

    Examples:

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

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

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

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

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

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

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

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

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

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

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

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

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

    `$uIoControlCode` is an unsigned value [a `IOCTL_*` 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 )`
    Renames a file or directory. `$sOldName` is the name of the existing file or directory that is to be renamed. `$sNewName` is the new name to give the file or directory. Returns a true value if the move succeeds. For failure, returns a false value and sets `fileLastErorr()` and `$^E` to the reason for the failure.

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

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

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

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

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

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

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

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

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

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

    `$sMode` is string of zero or more letters from `"rwatb"`. These are translated into a combination `O_RDONLY` [`"r"`], `O_WRONLY` [`"w"`], `O_RDWR` [`"rw"`], `O_APPEND` [`"a"`], `O_TEXT` [`"t"`], and `O_BINARY` [`"b"`] flags [see the 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"`, or `"PhysicalDrive0"`. If `$sDosDeviceName` is `[]` [for `NULL`], the list of all DOS device names is returned instead.

    `$osTargetPath` will be assigned a string containing the list of definitions. The definitions are each `'\0'`-terminate and are concatenated into the string, most recent first, with an extra `'\0'` at the end of the whole string [see `GetLogicalDriveStrings` for a sample of this format].

    `$lTargetBuf` is the size [in bytes] of the buffer to allocate for `$osTargetPath`. See Buffer Sizes for more information.

    `$olTargetLen` is set to the number of bytes written to `$osTargetPath` but you can also use `length($osTargetPath)` to determine this.

    For failure, `0` is returned and `fileLastError()` and `$^E` are set to the reason for the failure.

  ReadFile
  `ReadFile( $hFile, $opBuffer, $lBytes, $olBytesRead, $pOverlapped )`
    Reads bytes from a file or file-like device. Returns a true value if the read operation was successful. For failure, returns a false value and sets `fileLastError()` and `$^E` for the reason for the failure.

    `$hFile` is a Win32 native file handle that is already open to the file or device to read from.

    `$opBuffer` will be set to a string containing the bytes read.

    `$lBytes` is the number of bytes you would like to read. `$opBuffer` is automatically initialized to have a buffer large enough to hold that many bytes. Unlike other buffer sizes, `$lBytes` does not need to have a `"="` prepended to it to prevent a larger value to be passed to the underlying Win32 `ReadFile` API. However, a leading `"="` will be silently ignored, even if Perl warnings are enabled.

    If `$olBytesRead` is not `[]`, it will be set to the actual number of bytes read, though `length($opBuffer)` can also be used to determine this.

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

  SetErrorMode
  `$uOldMode= SetErrorMode( $uNewMode )`
    Sets the mode controlling system error handling and returns the previous mode value. Both `$uOldMode` and `$uNewMode` will have zero or more of the following bits set:
    `SEM_FAILCRITICALERRORS`
      If set, indicates that when a critical error is encountered, the call that triggered the error fails immediately. Normally this bit is not set, which means that a critical error causes a dialogue box to appear notifying the desktop user that some application has triggered a critical error. The dialogue box allows the desktop user to decide whether the critical error is returned to the process, is ignored, or the offending operation is retried.

      This affects the `CreateFile` and `GetVolumeInformation` calls.

      Setting this bit is useful for allowing you to check whether a floppy diskette is in the floppy drive.

    `SEM_NOALIGNMENTFAULTEXCEPT`
      If set, this causes memory access misalignment faults to be automatically fixed in a manner invisible to the process. This flag is ignored on x86-based versions of Windows NT. This flag is not supported on Windows 95.

    `SEM_NOGPFAULTERRORBOX`
      If set, general protection faults do not generate a dialogue box but can instead be handled by the process via an exception handler. This bit should not be set by programs that don't know how to handle such faults.

    `SEM_NOOPENFILEERRORBOX`
      If set, then when an attempt to continue reading from or writing to an already open file [usually on a removable medium like a floppy diskette] finds the file no longer available, the call will immediately fail. Normally this bit is not set, which means that instead a dialogue box will appear notifying the desktop user that some application has run into this problem. The dialogue box allows the desktop user to decide whether the failure is returned to the process, is ignored, or the offending operation is retried.

      This affects the `ReadFile` and `WriteFile` calls.

  SetFilePointer
  `$uNewPos= SetFilePointer( $hFile, $ivOffset, $ioivOffsetHigh, $uFromWhere )`
    The native Win32 version of `seek()`. `SetFilePointer` sets the position within a file where the next read or write operation will start from.

    `$hFile` is a Win32 native file handle.

    `$uFromWhere` is either `FILE_BEGIN`, `FILE_CURRENT`, or `FILE_END`, indicating that the new file position is being specified relative to the beginning of the file, the current file pointer, or the end of the file, respectively.

    `$ivOffset` is [if `$ioivOffsetHigh` is `[]`] the offset [in bytes] to the new file position from the position specified via `$uFromWhere`. If `$ioivOffsetHigh` is not `[]`, then `$ivOffset` is converted to an unsigned value to be used as the low-order 4 bytes of the offset.

    `$ioivOffsetHigh` can be `[]` [for `NULL`] to indicate that you are only specifying a 4-byte offset and the resulting file position will be 0xFFFFFFFE or less [just under 4GB]. Otherwise `$ioivOfffsetHigh` starts out with the high-order 4 bytes [signed] of the offset and gets set to the [unsigned] high-order 4 bytes of the resulting file position.

    The underlying `SetFilePointer` returns `0xFFFFFFFF` to indicate failure, but if `$ioivOffsetHigh` is not `[]`, you would also have to check `$^E` to determine whether `0xFFFFFFFF` indicates an error or not. `Win32API::File::SetFilePointer` does this checking for you and returns a false value if and only if the underlying `SetFilePointer` failed. For this reason, `$uNewPos` is set to `"0 but true"` if you set the file pointer to the beginning of the file [or any position with 0 for the low-order 4 bytes].

    So the return value will be true if the seek operation was successful. For failure, a false value is returned and `fileLastError()` and `$^E` are set to the reason for the failure.

  SetHandleInformation
  `SetHandleInformation( $hObject, $uMask, $uFlags )`
    Sets the flags associated with a Win32 native file handle or object handle. Returns a true value if the operation was successful. For failure, returns a false value and sets `fileLastError()` and `$^E` for the reason for the failure.

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

    `$uMask` is an unsigned value having one or more of the bits `HANDLE_FLAG_INHERIT` and `HANDLE_FLAG_PROTECT_FROM_CLOSE` set. Only bits set in `$uMask` will be modified by `SetHandleInformation`.

    `$uFlags` is an unsigned value having zero or more of the bits `HANDLE_FLAG_INHERIT` and `HANDLE_FLAG_PROTECT_FROM_CLOSE` set. For each bit set in `$uMask`, the cooresponding bit in the handle's flags is set to the value of the cooresponding bit in `$uFlags`.

    If `$uOldFlags` were the value of the handle's flags before the call to `SetHandleInformation`, then the value of the handle's flags afterward would be:

            ( $uOldFlags & ~$uMask ) | ( $uFlags & $uMask )

    [at least as far as the `HANDLE_FLAG_INHERIT` and `HANDLE_FLAG_PROTECT_FROM_CLOSE` bits are concerned.]

    See the `":HANDLE_FLAG_"` export class for the meanings of these bits.

  WriteFile
  `WriteFile( $hFile, $pBuffer, $lBytes, $ouBytesWritten, $pOverlapped )`
    Write bytes to a file or file-like device. Returns a true value if the operation was successful. For failure, returns a false value and sets `fileLastError()` and `$^E` for the reason for the failure.

    `$hFile` is a Win32 native file handle that is already open to the file or device to be written to.

    `$pBuffer` is a string containing the bytes to be written.

    `$lBytes` is the number of bytes you would like to write. If `$pBuffer` is not at least `$lBytes` long, `WriteFile` croaks. You can specify `0` for `$lBytes` to write `length($pBuffer)` bytes. A leading `"="` on `$lBytes` will be silently ignored, even if Perl warnings are enabled.

    `$ouBytesWritten` will be set to the actual number of bytes written unless you specify it as `[]`.

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

`":FuncA"`
  The ASCII-specific functions. Each of these is just the same as the version without the trailing ``A''.

              CopyFileA
              CreateFileA
              DefineDosDeviceA
              DeleteFileA
              GetDriveTypeA
              GetLogicalDriveStringsA
              GetVolumeInformationA
              MoveFileA
              MoveFileExA
              QueryDosDeviceA

`":FuncW"`
  The wide-character-specific (Unicode) functions. Each of these is just the same as the version without the trailing ``W'' except that strings are expected in Unicode and some lengths are measured as number of `WCHAR`s instead of number of bytes, as indicated below.
  CopyFileW
  `CopyFileW( $swOldFileName, $swNewFileName, $bFailIfExists )`
    `$swOldFileName` and `$swNewFileName` are Unicode strings.

  CreateFileW
  `$hObject= CreateFileW( $swPath, $uAccess, $uShare, $pSecAttr, $uCreate, $uFlags, $hModel )`
    `$swPath` is Unicode.

  DefineDosDeviceW
  `DefineDosDeviceW( $uFlags, $swDosDeviceName, $swTargetPath )`
    `$swDosDeviceName` and `$swTargetPath` are Unicode.

  DeleteFileW
  `DeleteFileW( $swFileName )`
    `$swFileName` is Unicode.

  GetDriveTypeW
  `$uDriveType= GetDriveTypeW( $swRootPath )`
    `$swRootPath` is Unicode.

  GetLogicalDriveStringsW
  `$olwOutLength= GetLogicalDriveStringsW( $lwBufSize, $oswBuffer )`
    Unicode is stored in `$oswBuffer`. `$lwBufSize` and `$olwOutLength` are measured as number of `WCHAR`s.

  GetVolumeInformationW
  `GetVolumeInformationW( $swRootPath, $oswVolName, $lwVolName, $ouSerialNum, $ouMaxNameLen, $ouFsFlags, $oswFsType, $lwFsType )`
    `$swRootPath` is Unicode and Unicode is written to `$oswVolName` and `$oswFsType`. `$lwVolName` and `$lwFsType` are measures as number of `WCHAR`s.

  MoveFileW
  `MoveFileW( $swOldName, $swNewName )`
    `$swOldName` and `$swNewName` are Unicode.

  MoveFileExW
  `MoveFileExW( $swOldName, $swNewName, $uFlags )`
    `$swOldName` and `$swNewName` are Unicode.

  QueryDosDeviceW
  `$olwTargetLen= QueryDosDeviceW( $swDeviceName, $oswTargetPath, $lwTargetBuf )`
    `$swDeviceName` is Unicode and Unicode is written to `$oswTargetPath`. `$lwTargetBuf` and `$olwTargetLen` are measured as number of `WCHAR`s.

`":Misc"`
  Miscellaneous constants. Used for the `$uCreate` argument of `CreateFile` or the `$uFromWhere` argument of `SetFilePointer`. Plus `INVALID_HANDLE_VALUE`, which you usually won't need to check for since most routines translate it into a false value.

              CREATE_ALWAYS           CREATE_NEW              OPEN_ALWAYS
              OPEN_EXISTING           TRUNCATE_EXISTING       INVALID_HANDLE_VALUE
              FILE_BEGIN              FILE_CURRENT            FILE_END

`":DDD_"`
  Constants for the `$uFlags` argument of `DefineDosDevice`.

              DDD_EXACT_MATCH_ON_REMOVE
              DDD_RAW_TARGET_PATH
              DDD_REMOVE_DEFINITION

`":DRIVE_"`
  Constants returned by `GetDriveType`.

              DRIVE_UNKNOWN           DRIVE_NO_ROOT_DIR       DRIVE_REMOVABLE
              DRIVE_FIXED             DRIVE_REMOTE            DRIVE_CDROM
              DRIVE_RAMDISK

`":FILE_"`
  Specific types of access to files that can be requested via the `$uAccess` argument to `CreateFile`.

              FILE_READ_DATA                  FILE_LIST_DIRECTORY
              FILE_WRITE_DATA                 FILE_ADD_FILE
              FILE_APPEND_DATA                FILE_ADD_SUBDIRECTORY
              FILE_CREATE_PIPE_INSTANCE       FILE_READ_EA
              FILE_WRITE_EA                   FILE_EXECUTE
              FILE_TRAVERSE                   FILE_DELETE_CHILD
              FILE_READ_ATTRIBUTES            FILE_WRITE_ATTRIBUTES
              FILE_ALL_ACCESS                 FILE_GENERIC_READ
              FILE_GENERIC_WRITE              FILE_GENERIC_EXECUTE )],

`":FILE_ATTRIBUTE_"`
  File attribute constants. Returned by `attrLetsToBits` and used in the `$uFlags` argument to `CreateFile`.

              FILE_ATTRIBUTE_ARCHIVE          FILE_ATTRIBUTE_COMPRESSED
              FILE_ATTRIBUTE_HIDDEN           FILE_ATTRIBUTE_NORMAL
              FILE_ATTRIBUTE_OFFLINE          FILE_ATTRIBUTE_READONLY
              FILE_ATTRIBUTE_SYSTEM           FILE_ATTRIBUTE_TEMPORARY

`":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_SHARE_"`
  File sharing constants. Used in the `$uShare` argument to `CreateFile`.

              FILE_SHARE_DELETE       FILE_SHARE_READ         FILE_SHARE_WRITE

`":FILE_TYPE_"`
  File type constants. Returned by `GetFileType`.

              FILE_TYPE_CHAR          FILE_TYPE_DISK
              FILE_TYPE_PIPE          FILE_TYPE_UNKNOWN

`":FS_"`
  File system characteristics constants. Placed in the `$ouFsFlags` argument to `GetVolumeInformation`.

              FS_CASE_IS_PRESERVED            FS_CASE_SENSITIVE
              FS_UNICODE_STORED_ON_DISK       FS_PERSISTENT_ACLS
              FS_FILE_COMPRESSION             FS_VOL_IS_COMPRESSED

`":HANDLE_FLAG_"`
  Flag bits modifying the behavior of an object handle and accessed via `GetHandleInformation` and `SetHandleInformation`.
  HANDLE_FLAG_INHERIT
    If this bit is set, then children of this process who inherit handles [that is, processes created by calls to the Win32 `CreateProcess` API with the `bInheritHandles` parameter specified as `TRUE`], will inherit this particular object handle.

  HANDLE_FLAG_PROTECT_FROM_CLOSE
    If this bit is set, then calls to `CloseHandle` against this handle will be ignored, leaving the handle open and usable.

`":IOCTL_STORAGE_"`
  I/O control operations for generic storage devices. Used in the `$uIoControlCode` argument to `DeviceIoControl`. Includes `IOCTL_STORAGE_CHECK_VERIFY`, `IOCTL_STORAGE_MEDIA_REMOVAL`, `IOCTL_STORAGE_EJECT_MEDIA`, `IOCTL_STORAGE_LOAD_MEDIA`, `IOCTL_STORAGE_RESERVE`, `IOCTL_STORAGE_RELEASE`, `IOCTL_STORAGE_FIND_NEW_DEVICES`, and `IOCTL_STORAGE_GET_MEDIA_TYPES`.
  `IOCTL_STORAGE_CHECK_VERIFY`
    Verify that a device's media is accessible. `$pInBuf` and `$opOutBuf` should both be `[]`. If `DeviceIoControl` returns a true value, then the media is currently accessible.

  `IOCTL_STORAGE_MEDIA_REMOVAL`
    Allows the device's media to be locked or unlocked. `$opOutBuf` should be `[]`. `$pInBuf` should be a `PREVENT_MEDIA_REMOVAL` data structure, which is simply an interger containing a boolean value:

            $pInBuf= pack( "i", $bPreventMediaRemoval );

  `IOCTL_STORAGE_EJECT_MEDIA`
    Requests that the device eject the media. `$pInBuf` and `$opOutBuf` should both be `[]`.

  `IOCTL_STORAGE_LOAD_MEDIA`
    Requests that the device load the media. `$pInBuf` and `$opOutBuf` should both be `[]`.

  `IOCTL_STORAGE_RESERVE`
    Requests that the device be reserved. `$pInBuf` and `$opOutBuf` should both be `[]`.

  `IOCTL_STORAGE_RELEASE`
    Releases a previous device reservation. `$pInBuf` and `$opOutBuf` should both be `[]`.

  `IOCTL_STORAGE_FIND_NEW_DEVICES`
    No documentation on this IOCTL operation was found.

  `IOCTL_STORAGE_GET_MEDIA_TYPES`
    Requests information about the type of media supported by the device. `$pInBuf` should be `[]`. `$opOutBuf` will be set to contain a vector of `DISK_GEOMETRY` data structures, which can be decoded via:

            # Calculate the number of DISK_GEOMETRY structures returned:
            my $cStructs= length($opOutBuf)/(4+4+4+4+4+4);
            my @fields= unpack( "L l I L L L" x $cStructs, $opOutBuf )
            my( @ucCylsLow, @ivcCylsHigh, @uMediaType, @uTracksPerCyl,
              @uSectsPerTrack, @uBytesPerSect )= ();
            while(  @fields  ) {
                push( @ucCylsLow, unshift @fields );
                push( @ivcCylsHigh, unshift @fields );
                push( @uMediaType, unshift @fields );
                push( @uTracksPerCyl, unshift @fields );
                push( @uSectsPerTrack, unshift @fields );
                push( @uBytesPerSect, unshift @fields );
            }

    For the `$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 superceded but is still useful when used on a floppy device like `"//./A:"`.

  Includes `IOCTL_DISK_FORMAT_TRACKS`, `IOCTL_DISK_FORMAT_TRACKS_EX`, `IOCTL_DISK_GET_DRIVE_GEOMETRY`, `IOCTL_DISK_GET_DRIVE_LAYOUT`, `IOCTL_DISK_GET_MEDIA_TYPES`, `IOCTL_DISK_GET_PARTITION_INFO`, `IOCTL_DISK_HISTOGRAM_DATA`, `IOCTL_DISK_HISTOGRAM_RESET`, `IOCTL_DISK_HISTOGRAM_STRUCTURE`, `IOCTL_DISK_IS_WRITABLE`, `IOCTL_DISK_LOGGING`, `IOCTL_DISK_PERFORMANCE`, `IOCTL_DISK_REASSIGN_BLOCKS`, `IOCTL_DISK_REQUEST_DATA`, `IOCTL_DISK_REQUEST_STRUCTURE`, `IOCTL_DISK_SET_DRIVE_LAYOUT`, `IOCTL_DISK_SET_PARTITION_INFO`, and `IOCTL_DISK_VERIFY`.

  `IOCTL_DISK_GET_DRIVE_GEOMETRY`
    Request information about the size and geometry of the disk. `$pInBuf` should be `[]`. `$opOutBuf` will be set to a `DISK_GEOMETRY` data structure which can be decode via:

            ( $ucCylsLow, $ivcCylsHigh, $uMediaType, $uTracksPerCyl,
              $uSectsPerTrack, $uBytesPerSect )= unpack( "L l I L L L", $opOutBuf );

    `$ucCylsLow`
      The low-order 4 bytes of the total number of cylinders.

    `$ivcCylsHigh`
      The high-order 4 bytes of the total number of cylinders.

    `$uMediaType`
      A code for the type of media. See the `":MEDIA_TYPE"` export class.

    `$uTracksPerCyl`
      The number of tracks in each cylinder.

    `$uSectsPerTrack`
      The number of sectors in each track.

    `$uBytesPerSect`
      The number of bytes in each sector.

  `IOCTL_DISK_GET_PARTITION_INFO`
    Request information about the size and geometry of the partition. `$pInBuf` should be `[]`. `$opOutBuf` will be set to a `PARTITION_INFORMATION` data structure which can be decode via:

            ( $uStartLow, $ivStartHigh, $ucHiddenSects, $uPartitionSeqNumber,
              $uPartitionType, $bActive, $bRecognized, $bToRewrite )=
              unpack( "L l L L C c c c", $opOutBuf );

    `$uStartLow` and `$ivStartHigh`
      The low-order and high-order [respectively] 4 bytes of the starting offset of the partition, measured in bytes.

    `$ucHiddenSects`
      The number of ``hidden'' sectors for this partition. Actually this is the number of sectors found prior to this partiton, that is, the starting offset [as found in `$uStartLow` and `$ivStartHigh`] divided by the number of bytes per sector.

    `$uPartitionSeqNumber`
      The sequence number of this partition. Partitions are numbered starting as `1` [with ``partition 0'' meaning the entire disk]. Sometimes this field may be `0` and you'll have to infer the partition sequence number from how many partitions preceed it on the disk.

    `$uPartitionType`
      The type of partition. See the `":PARTITION_"` export class for a list of known types. See also `IsRecognizedPartition` and `IsContainerPartition`.

    `$bActive`
      `1` for the active [boot] partition, `0` otherwise.

    `$bRecognized`
      Whether this type of partition is support under Win32.

    `$bToRewrite`
      Whether to update this partition information. This field is not used by `IOCTL_DISK_GET_PARTITION_INFO`. For `IOCTL_DISK_SET_DRIVE_LAYOUT`, you must set this field to a true value for any partitions you wish to have changed, added, or deleted.

  `IOCTL_DISK_SET_PARTITION_INFO`
    Change the type of the partition. `$opOutBuf` should be `[]`. `$pInBuf` should be a `SET_PARTITION_INFORMATION` data structure which is just a single byte containing the new parition type [see the `":PARTITION_"` export class for a list of known types]:

            $pInBuf= pack( "C", $uPartitionType );

  `IOCTL_DISK_GET_DRIVE_LAYOUT`
    Request information about the disk layout. `$pInBuf` should be `[]`. `$opOutBuf` will be set to contain `DRIVE_LAYOUT_INFORMATION` structure including several `PARTITION_INFORMATION` structures:

            my( $cPartitions, $uDiskSignature )= unpack( "L L", $opOutBuf );
            my @fields= unpack( "x8" . ( "L l L L C c c c" x $cPartitions ),
                                $opOutBuf );
            my( @uStartLow, @ivStartHigh, @ucHiddenSects,
              @uPartitionSeqNumber, @uPartitionType, @bActive,
              @bRecognized, @bToRewrite )= ();
            for(  1..$cPartition  ) {
                push( @uStartLow, unshift @fields );
                push( @ivStartHigh, unshift @fields );
                push( @ucHiddenSects, unshift @fields );
                push( @uPartitionSeqNumber, unshift @fields );
                push( @uPartitionType, unshift @fields );
                push( @bActive, unshift @fields );
                push( @bRecognized, unshift @fields );
                push( @bToRewrite, unshift @fields );
            }

    `$cPartitions`
      If the number of partitions on the disk.

    `$uDiskSignature`
      Is the disk signature, a unique number assigned by Disk Administrator [WinDisk.exe] and used to identify the disk. This allows drive letters for partitions on that disk to remain constant even if the SCSI Target ID of the disk gets changed.

    See `IOCTL_DISK_GET_PARTITION_INFORMATION` for information on the remaining these fields.

  `IOCTL_DISK_GET_MEDIA_TYPES`
    Is supposed to be superseded by `IOCTL_STORAGE_GET_MEDIA_TYPES` but is still useful for determining the types of floppy diskette formats that can be produced by a given floppy drive. See ex/FormatFloppy.plx for an example.

  `IOCTL_DISK_SET_DRIVE_LAYOUT`
    Change the partition layout of the disk. `$pOutBuf` should be `[]`. `$pInBuf` should be a `DISK_LAYOUT_INFORMATION` data structure including several `PARTITION_INFORMATION` data structures.

            # Already set:  $cPartitions, $uDiskSignature, @uStartLow, @ivStartHigh,
            #   @ucHiddenSects, @uPartitionSeqNumber, @uPartitionType, @bActive,
            #   @bRecognized, and @bToRewrite.
            my( @fields, $prtn )= ();
            for $prtn (  1..$cPartition  ) {
                push( @fields, $uStartLow[$prtn-1], $ivStartHigh[$prtn-1],
                    $ucHiddenSects[$prtn-1], $uPartitionSeqNumber[$prtn-1],
                    $uPartitionType[$prtn-1], $bActive[$prtn-1],
                    $bRecognized[$prtn-1], $bToRewrite[$prtn-1] );
            }
            $pInBuf= pack( "L L" . ( "L l L L C c c c" x $cPartitions ),
                           $cPartitions, $uDiskSignature, @fields );

    To delete a partition, zero out all fields except for `$bToRewrite` which should be set to `1`. To add a partition, increment `$cPartitions` and add the information for the new partition into the arrays, making sure that you insert `1` into @bToRewrite.

    See `IOCTL_DISK_GET_DRIVE_LAYOUT` and `IOCTL_DISK_GET_PARITITON_INFORMATION` for descriptions of the fields.

  `IOCTL_DISK_VERIFY`
    Performs a logical format of [part of] the disk. `$opOutBuf` should be `[]`. `$pInBuf` should contain a `VERIFY_INFORMATION` data structure:

            $pInBuf= pack( "L l L",
                           $uStartOffsetLow, $ivStartOffsetHigh, $uLength );

    `$uStartOffsetLow` and `$ivStartOffsetHigh`
      The low-order and high-order [respectively] 4 bytes of the offset [in bytes] where the formatting should begin.

    `$uLength`
      The length [in bytes] of the section to be formatted.

  `IOCTL_DISK_FORMAT_TRACKS`
    Format a range of tracks on the disk. `$opOutBuf` should be `[]`. `$pInBuf` should contain a `FORMAT_PARAMETERS` data structure:

            $pInBuf= pack( "L L L L L", $uMediaType,
                           $uStartCyl, $uEndCyl, $uStartHead, $uEndHead );

    `$uMediaType` if the type of media to be formatted. Mostly used to specify the density to use when formatting a floppy diskette. See the `":MEDIA_TYPE"` export class for more information.

    The remaining fields specify the starting and ending cylinder and head of the range of tracks to be formatted.

  `IOCTL_DISK_REASSIGN_BLOCKS`
    Reassign a list of disk blocks to the disk's spare-block pool. `$opOutBuf` should be `[]`. `$pInBuf` should be a `REASSIGN_BLOCKS` data structure:

            $pInBuf= pack( "S S L*", 0, $cBlocks, @uBlockNumbers );

  `IOCTL_DISK_PERFORMANCE`
    Request information about disk performance. `$pInBuf` should be `[]`. `$opOutBuf` will be set to contain a `DISK_PERFORMANCE` data structure:

            my( $ucBytesReadLow, $ivcBytesReadHigh,
                $ucBytesWrittenLow, $ivcBytesWrittenHigh,
                $uReadTimeLow, $ivReadTimeHigh,
                $uWriteTimeLow, $ivWriteTimeHigh,
                $ucReads, $ucWrites, $uQueueDepth )=
                unpack( "L l L l L l L l L L L", $opOutBuf );

  `IOCTL_DISK_IS_WRITABLE`
    No documentation on this IOCTL operation was found.

  `IOCTL_DISK_LOGGING`
    Control disk logging. Little documentation for this IOCTL operation was found. It makes use of a `DISK_LOGGING` data structure:
    DISK_LOGGING_START
      Start logging each disk request in a buffer internal to the disk device driver of size `$uLogBufferSize`:

              $pInBuf= pack( "C L L", 0, 0, $uLogBufferSize );

    DISK_LOGGING_STOP
      Stop loggin each disk request:

              $pInBuf= pack( "C L L", 1, 0, 0 );

    DISK_LOGGING_DUMP
      Copy the interal log into the supplied buffer:

              $pLogBuffer= ' ' x $uLogBufferSize
              $pInBuf= pack( "C P L", 2, $pLogBuffer, $uLogBufferSize );

              ( $uByteOffsetLow[$i], $ivByteOffsetHigh[$i],
                $uStartTimeLow[$i], $ivStartTimeHigh[$i],
                $uEndTimeLog[$i], $ivEndTimeHigh[$i],
                $hVirtualAddress[$i], $ucBytes[$i],
                $uDeviceNumber[$i], $bWasReading[$i] )=
                unpack( "x".(8+8+8+4+4+1+1+2)." L l L l L l L L C c x2", $pLogBuffer );

    DISK_LOGGING_BINNING
      Keep statics grouped into bins based on request sizes.

              $pInBuf= pack( "C P L", 3, $pUnknown, $uUnknownSize );

  `IOCTL_DISK_FORMAT_TRACKS_EX`
    No documentation on this IOCTL is included.

  `IOCTL_DISK_HISTOGRAM_STRUCTURE`
    No documentation on this IOCTL is included.

  `IOCTL_DISK_HISTOGRAM_DATA`
    No documentation on this IOCTL is included.

  `IOCTL_DISK_HISTOGRAM_RESET`
    No documentation on this IOCTL is included.

  `IOCTL_DISK_REQUEST_STRUCTURE`
    No documentation on this IOCTL operation was found.

  `IOCTL_DISK_REQUEST_DATA`
    No documentation on this IOCTL operation was found.

`":GENERIC_"`
  Constants specifying generic access permissions that are not specific to one type of object.

              GENERIC_ALL                     GENERIC_EXECUTE
              GENERIC_READ                    GENERIC_WRITE

`":MEDIA_TYPE"`
  Different classes of media that a device can support. Used in the `$uMediaType` field of a `DISK_GEOMETRY` structure.
  `Unknown`
    Format is unknown.

  `F5_1Pt2_512`
    5.25`` floppy, 1.2MB [really 1,200KB] total space, 512 bytes/sector.

  `F3_1Pt44_512`
    3.5`` floppy, 1.44MB [really 1,440KB] total space, 512 bytes/sector.

  `F3_2Pt88_512`
    3.5`` floppy, 2.88MB [really 2,880KB] total space, 512 bytes/sector.

  `F3_20Pt8_512`
    3.5`` floppy, 20.8MB total space, 512 bytes/sector.

  `F3_720_512`
    3.5`` floppy, 720KB total space, 512 bytes/sector.

  `F5_360_512`
    5.25`` floppy, 360KB total space, 512 bytes/sector.

  `F5_320_512`
    5.25`` floppy, 320KB total space, 512 bytes/sector.

  `F5_320_1024`
    5.25`` floppy, 320KB total space, 1024 bytes/sector.

  `F5_180_512`
    5.25`` floppy, 180KB total space, 512 bytes/sector.

  `F5_160_512`
    5.25`` floppy, 160KB total space, 512 bytes/sector.

  `RemovableMedia`
    Some type of removable media other than a floppy diskette.

  `FixedMedia`
    A fixed hard disk.

  `F3_120M_512`
    3.5`` floppy, 120MB total space.

`":MOVEFILE_"`
  Constants for use in `$uFlags` arguments to `MoveFileEx`.

              MOVEFILE_COPY_ALLOWED           MOVEFILE_DELAY_UNTIL_REBOOT
              MOVEFILE_REPLACE_EXISTING       MOVEFILE_WRITE_THROUGH

`":SECURITY_"`
  Security quality of service values that can be used in the `$uFlags` argument to `CreateFile` if opening the client side of a named pipe.

              SECURITY_ANONYMOUS              SECURITY_CONTEXT_TRACKING
              SECURITY_DELEGATION             SECURITY_EFFECTIVE_ONLY
              SECURITY_IDENTIFICATION         SECURITY_IMPERSONATION
              SECURITY_SQOS_PRESENT

`":SEM_"`
  Constants to be used with `SetErrorMode`.

              SEM_FAILCRITICALERRORS          SEM_NOGPFAULTERRORBOX
              SEM_NOALIGNMENTFAULTEXCEPT      SEM_NOOPENFILEERRORBOX

`":PARTITION_"`
  Constants describing partition types.

              PARTITION_ENTRY_UNUSED          PARTITION_FAT_12
              PARTITION_XENIX_1               PARTITION_XENIX_2
              PARTITION_FAT_16                PARTITION_EXTENDED
              PARTITION_HUGE                  PARTITION_IFS
              PARTITION_FAT32                 PARTITION_FAT32_XINT13
              PARTITION_XINT13                PARTITION_XINT13_EXTENDED
              PARTITION_PREP                  PARTITION_UNIX
              VALID_NTFT                      PARTITION_NTFT

`":ALL"`
  All of the above.

# BUGS

None known at this time.

# AUTHOR

Tye McQueen, tye@metronet.com, http://www.metronet.com/~tye/.

# SEE ALSO

The pyramids.

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