file.pm

source of perl for linux application,

      or  die "Can't create temporary file, temp.$$: $^E\n";

=item getLogicalDrives

=item C<@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 C<("A:\\","C:\\")>.

=item CloseHandle

=item C<CloseHandle( $hObject )>

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

=item CopyFile

=item C<CopyFile( $sOldFileName, $sNewFileName, $bFailIfExists )>

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

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

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

=item CreateFile

=item C<$hObject= CreateFile( $sPath, $uAccess, $uShare, $pSecAttr, $uCreate, $uFlags, $hModel )>

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

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

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

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

C<$sPath> can start with C<"//./"> to indicate that the rest of the
path is the name of a "DOS device."  You can use C<QueryDosDevice>
to list all current DOS devices and can add or delete them with
C<DefineDosDevice>.  If you get the source-code distribution of this
module from CPAN, then it includes an example script, F<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:

=over

=item C<"//./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
C<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 C<0> for C<$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.

=item C<"//./C:">

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

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

=item C<"//./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
C<DeviceIoControl> to perform miscellaneous queries and operations
to the floopy disk or drive.

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

=item C<"//./PIPE/PipeName">

A named pipe, created via C<CreateNamedPipe>.

=back

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

C<$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.  C<$uShare> is an unsigned value with zero or more
of these bits set:  C<FILE_SHARE_READ>, C<FILE_SHARE_WRITE>, and
C<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
C<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 C<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.

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

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

then you can set C<$pSecAttr> via:

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

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

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

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

C<$hModel> is C<0> [or C<[]>, both of which mean C<NULL>] or a Win32
native handle opened with C<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";

=item DefineDosDevice

=item C<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 C<$^E>
and C<regLastError()>] on failure.

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

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

=over

=item C<DDD_RAW_TARGET_PATH>

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

=item C<DDD_REMOVE_DEFINITION>

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

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

=item C<DDD_EXACT_MATCH_ON_REMOVE>

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

=back

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

=item DeleteFile

=item C<DeleteFile( $sFileName )>

Deletes the named file.  Compared to Perl's C<unlink>, C<DeleteFile>
has the advantage of not deleting read-only files.  For B<some>
versions of Perl, C<unlink> silently calls C<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 C<unlink>.

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

=item DeviceIoControl

=item C<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 C<$^E> and
C<regLastError()>] on failure.

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

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

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

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

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

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

=item FdGetOsFHandle

=item C<$hNativeHandle= FdGetOsFHandle( $ivFd )>

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

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

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

=item fileConstant

=item C<$value= fileConstant( $sConstantName )>

Fetch the value of a constant.  Returns C<undef> if C<$sConstantName>
is not the name of a constant supported by this module.  Never sets
C<$!> nor C<$^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 C<use Win32API::File> statement and then
simply using the constant name in your code [perhaps followed by
C<()>].  This function is useful for verifying constant names not in
Perl code, for example, after prompting a user to type in a constant
name.

=item fileLastError

=item C<$svError= fileLastError();>

=item C<fileLastError( $uError );>

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

Just like C<$^E>, in a numeric context C<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 C<$x= fileLastError()> causes C<$x>
to give different values in string vs. numeric contexts].

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

=item GetDriveType

=item C<$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:

=over

=item C<DRIVE_UNKNOWN>

None of the following.

=item C<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.

=item C<DRIVE_REMOVABLE>

A floppy diskette drive or other removable media drive, but not a CD-ROM
drive.

=item C<DRIVE_FIXED>

An ordinary hard disk partition.

=item C<DRIVE_REMOTE>

A network share.

=item C<DRIVE_CDROM>

A CD-ROM drive.

=item C<DRIVE_RAMDISK>

A "ram disk" or memory-resident virtual file system used for high-speed
access to small amounts of temporary file space.

=back

=item GetFileAttributes

=item C<$uAttrs = GetFileAttributes( $sPath )>

Takes a path string and returns an unsigned value with attribute flags.
If it fails, it returns INVALID_FILE_ATTRIBUTES, otherwise it can be
one or more of the following values:

=over