file.pm

source of perl for linux application,

=item C<FILE_ATTRIBUTE_ARCHIVE>

The file or directory is an archive file or directory. Applications use
this attribute to mark files for backup or removal.

=item C<FILE_ATTRIBUTE_COMPRESSED>

The file or directory is compressed. For a file, this means that all of
the data in the file is compressed. For a directory, this means that
compression is the default for newly created files and subdirectories. 

=item C<FILE_ATTRIBUTE_DEVICE>

Reserved; do not use. 

=item C<FILE_ATTRIBUTE_DIRECTORY>

The handle identifies a directory. 

=item C<FILE_ATTRIBUTE_ENCRYPTED>

The file or directory is encrypted. For a file, this means that all data
streams in the file are encrypted. For a directory, this means that
encryption is the default for newly created files and subdirectories. 

=item C<FILE_ATTRIBUTE_HIDDEN>

The file or directory is hidden. It is not included in an ordinary directory
listing. 

=item C<FILE_ATTRIBUTE_NORMAL>

The file or directory has no other attributes set. This attribute is valid
only if used alone. 

=item C<FILE_ATTRIBUTE_NOT_CONTENT_INDEXED>

The file will not be indexed by the content indexing service. 

=item C<FILE_ATTRIBUTE_OFFLINE>

The data of the file is not immediately available. This attribute indicates
that the file data has been physically moved to offline storage. This
attribute is used by Remote Storage, the hierarchical storage management
software. Applications should not arbitrarily change this attribute. 

=item C<FILE_ATTRIBUTE_READONLY>

The file or directory is read-only. Applications can read the file but cannot
write to it or delete it. In the case of a directory, applications cannot
delete it. 

=item C<FILE_ATTRIBUTE_REPARSE_POINT>

The file or directory has an associated reparse point. 

=item C<FILE_ATTRIBUTE_SPARSE_FILE>

The file is a sparse file. 

=item C<FILE_ATTRIBUTE_SYSTEM>

The file or directory is part of, or is used exclusively by, the operating
system. 

=item C<FILE_ATTRIBUTE_TEMPORARY>

The file is being used for temporary storage. File systems avoid writing
data back to mass storage if sufficient cache memory is available, because
often the application deletes the temporary file shortly after the handle is
closed. In that case, the system can entirely avoid writing the data.
Otherwise, the data will be written after the handle is closed. 

=back

=item GetFileType

=item C<$uFileType= GetFileType( $hFile )>

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

=over

=item C<FILE_TYPE_UNKNOWN>

None of the below.  Often a special device.

=item C<FILE_TYPE_DISK>

An ordinary disk file.

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

=item C<FILE_TYPE_PIPE>

Either a named or anonymous pipe.

=back

=item getFileSize

=item C<$size= getFileSize( $hFile )>

This is a Perl-friendly wrapper for the C<GetFileSize> (below) API call.

It takes a Win32 native file handle and returns the size in bytes. Since the
size can be a 64 bit value, on non 64 bit integer Perls the value returned will
be an object of type C<Math::BigInt>.

=item GetFileSize

=item C<$iSizeLow= GetFileSize($win32Handle, $iSizeHigh)>

Returns the size of a file pointed to by C<$win32Handle>, optionally storing
the high order 32 bits into C<$iSizeHigh> if it is not C<[]>. If $iSizeHigh is
C<[]>, a non-zero value indicates success. Otherwise, on failure the return
value will be C<0xffffffff> and C<fileLastError()> will not be C<NO_ERROR>.

=item GetOverlappedResult

=item C<$bRetval= GetOverlappedResult( $win32Handle, $pOverlapped,
 $numBytesTransferred, $bWait )>

Used for asynchronous IO in Win32 to get the result of a pending IO operation,
such as when a file operation returns C<ERROR_IO_PENDING>. Returns a false
value on failure. The C<$overlapped> structure and C<$numBytesTransferred>
will be modified with the results of the operation.

As far as creating the C<$pOverlapped> structure, you are currently on your own.

See L<http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dllproc/base/getoverlappedresult.asp> for more information.

=item GetLogicalDrives

=item C<$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 C<1> bit
will be set in C<$uDriveBits>.  If "B:" is valid, then the C<2> bit will
be set.  If "Z:" is valid, then the C<2**26> [C<0x4000000>] bit will be
set.

=item GetLogicalDriveStrings

=item C<$olOutLength= GetLogicalDriveStrings( $lBufSize, $osBuffer )>

For each currently defined drive letter, a C<'\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 C<'\0'> is added.  This larger string is returned
in C<$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.

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

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

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

For example, on a poorly equipped computer,

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

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

=item GetHandleInformation

=item C<GetHandleInformation( $hObject, $ouFlags )>

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

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

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

=item GetOsFHandle

=item C<$hNativeHandle= GetOsFHandle( FILE )>

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

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

=item GetVolumeInformation

=item C<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
C<fileLastError()> and C<$^E>.

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

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

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

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

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

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

=over

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

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

=item C<FS_UNICODE_STORED_ON_DISK>

The file system preserves Unicode in file names [true for "NTFS"].

=item C<FS_PERSISTENT_ACLS>

The file system supports setting Access Control Lists on files [true
for "NTFS"].

=item C<FS_FILE_COMPRESSION>

The file system supports compression on a per-file basis [true for
"NTFS"].

=item C<FS_VOL_IS_COMPRESSED>

The entire file system is compressed such as via "DoubleSpace".

=back

=item IsRecognizedPartition

=item C<IsRecognizedPartition( $ivPartitionType )>

Takes a partition type and returns whether that partition type is
supported under Win32.  C<$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 C<PartitionType> member of the C<PARTITION_INFORMATION> structure.

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

=item IsContainerPartition

=item C<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. 
C<$ivPartitonType> is as for C<IsRecognizedPartition>.

=item MoveFile

=item C<MoveFile( $sOldName, $sNewName )>

Renames a file or directory.  C<$sOldName> is the name of the existing
file or directory that is to be renamed.  C<$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
C<fileLastErorr()> and C<$^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
C<$sNewName>, then C<MoveFile> will fail.

=item MoveFileEx

=item C<MoveFileEx( $sOldName, $sNewName, $uFlags )>

Renames a file or directory.  C<$sOldName> is the name of the existing
file or directory that is to be renamed.  C<$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
C<fileLastErorr()> and C<$^E> to the reason for the failure.

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

=over

=item C<MOVEFILE_REPLACE_EXISTING>

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

=item C<MOVEFILE_COPY_ALLOWED>

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

=item C<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, C<$sNewName> can be C<[]> [for C<NULL>] to
indicate that C<$sOldName> should be deleted during the next boot
rather than renamed.

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

=item C<MOVEFILE_WRITE_THROUGH>

Ensures that C<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.

=back

=item OsFHandleOpen

=item C<OsFHandleOpen( FILE, $hNativeHandle, $sMode )>

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

C<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 C<FILE> is already open, it will automatically
be closed before it is reopened.

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

C<$sMode> is string of zero or more letters from C<"rwatb">.  These
are translated into a combination C<O_RDONLY> [C<"r">], C<O_WRONLY>
[C<"w">], C<O_RDWR> [C<"rw">], C<O_APPEND> [C<"a">], C<O_TEXT>
[C<"t">], and C<O_BINARY> [C<"b">] flags [see the L<Fcntl> module]
that is passed to C<OsFHandleOpenFd>.   Currently only C<O_APPEND>
and C<O_TEXT> have any significance.

Also, a C<"r"> and/or C<"w"> in C<$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"

C<OsFHandleOpen> eventually calls the Win32-specific C routine
C<_open_osfhandle()> or Perl's "improved" version called
C<win32_open_osfhandle()>.  Prior to Perl5.005, C's
C<_open_osfhandle()> is called which will fail if
C