file.pm

source of perl for linux application,

sub DESTROY {}

# End of Tie/OO Interface

# Autoload methods go after =cut, and are processed by the autosplit program.

1;
__END__

=head1 NAME

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

=head1 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";
  [...]

=head1 DESCRIPTION

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

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

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 C<$^E> on failure.

=head2 Object Oriented/Tied Handle Interface

WARNING: this is new code, use at your own risk.

This version of C<Win32API::File> can be used like an C<IO::File> object:

  my $file = Win32API::File->new("+> foo");
  binmode $file;
  print $file "hello there\n";
  seek $file, 0, 0;
  my $line = <$file>;
  $file->close;

It also supports tying via a win32 handle (for example, from C<createFile()>):

  tie FILE, 'Win32API::File', $win32_handle;
  print FILE "...";

It has not been extensively tested yet and buffered I/O is not yet implemented.

=head2 Exports

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

=over

=item C<":Func">

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

=over

=item attrLetsToBits

=item C<$uBits= attrLetsToBits( $sAttributeLetters )>

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

=over

=item C<"a">

C<FILE_ATTRIBUTE_ARCHIVE>

=item C<"c">

C<FILE_ATTRIBUTE_COMPRESSED>

=item C<"h">

C<FILE_ATTRIBUTE_HIDDEN>

=item C<"o">

C<FILE_ATTRIBUTE_OFFLINE>

=item C<"r">

C<FILE_ATTRIBUTE_READONLY>

=item C<"s">

C<FILE_ATTRIBUTE_SYSTEM>

=item C<"t">

C<FILE_ATTRIBUTE_TEMPORARY>

=back

=item createFile

=item C<$hObject= createFile( $sPath )>

=item C<$hObject= createFile( $sPath, $rvhvOptions )>

=item C<$hObject= createFile( $sPath, $svAccess )>

=item C<$hObject= createFile( $sPath, $svAccess, $rvhvOptions )>

=item C<$hObject= createFile( $sPath, $svAccess, $svShare )>

=item C<$hObject= createFile( $sPath, $svAccess, $svShare, $rvhvOptions )>

This is a Perl-friendly wrapper around C<CreateFile>.

On failure, C<$hObject> gets set to a false value and C<regLastError()>
and C<$^E> are set to the reason for the failure.  Otherwise,
C<$hObject> gets set to a Win32 native file handle which is alwasy
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.  See
C<CreateFile> for more information on possible special values for
C<$sPath>.  

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

More likely, C<$svAccess> is a string describing the generic type of
access you desire and possibly the file creation options to use.  In
this case, C<$svAccess> should contain zero or more characters from
C<"qrw"> [access desired], zero or one character each from C<"ktn">
and C<"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 C<"?"> for C<$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.

C<$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 C<"k"> [and perhaps C<"e">, as in C<"w ke"> or C<"rw ke">]
since Win32 suggests C<OPEN_EXISTING> be used when opening a device.

=over

=item C<"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 C<"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
C<"q"> or C<"q ke"> may be easier to understand than just C<""> or C<"ke">.

=item C<"r">

Stands for "Read access".  Sets the C<GENERIC_READ> bit(s) in the
C<$uAccess> that is passed to C<CreateFile>.  This is the default
access if the C<$svAccess> parameter is missing [or if it is C<undef>
and C<$rvhvOptions> doesn't specify an C<"Access"> option].

=item C<"w">

Stands for "Write access".  Sets the C<GENERIC_WRITE> bit(s) in the
C<$uAccess> that is passed to C<CreateFile>.

=item C<"k">

Stands for "Keep if exists".  If the requested file exists, then it is
opened.  This is the default unless C<GENERIC_WRITE> access has been
requested but C<GENERIC_READ> access has not been requested.   Contrast
with C<"t"> and C<"n">.

=item C<"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
C<GENERIC_WRITE> access has been requested and C<GENERIC_READ> access
has not been requested.  Contrast with C<"k"> and C<"n">.

=item C<"n">

Stands for "New file only".  If the requested file exists, then it is
not opened and the C<createFile> call fails.  Contrast with C<"k"> and
C<"t">.  Can't be used with C<"e">.

=item C<"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 C<GENERIC_WRITE> access has been requested or if C<"t"> or
C<"n"> was specified.  Contrast with C<"e">.

=item C<"e">

Stands for "Existing file only".  If the requested file does not
exist, then nothing is opened and the C<createFile> call fails.  This
is the default unless C<GENERIC_WRITE> access has been requested or
C<"t"> or C<"n"> was specified.   Contrast with C<"c">.   Can't be
used with C<"n">.

=back

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

=over

=item C<"kc">

C<OPEN_ALWAYS>

=item C<"ke">

C<OPEN_EXISTING>

=item C<"tc">

C<TRUNCATE_EXISTING>

=item C<"te">

C<CREATE_ALWAYS>

=item C<"nc">

C<CREATE_NEW>

=item C<"ne">

Illegal.

=back

C<$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.  C<$svShare> will usually be a string containing zero
or more characters from C<"rwd"> but can also be a numeric bit mask.

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

The default for C<$svShare> is C<"rw"> which provides the same sharing as
using regular perl C<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
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, then 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<$rvhvOptions> is a reference to a hash where any keys must be from
the list C<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 C<$rvhvOptions> override the settings from
C<$svAccess> and C<$svShare> if they conflict.

=over

=item Flags => $uFlags

C<$uFlags> is an unsigned value having any of the C<FILE_FLAG_*> or
C<FILE_ATTRIBUTE_*> bits set.  Any C<FILE_ATTRIBUTE_*> bits set via the
C<Attributes> option are logically C<or>ed with these bits.  Defaults
to C<0>.

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

=item Attributes => $sAttributes

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

=item Security => $pSecurityAttributes

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

=item Model => $hModelFile

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

=item Access => $sAccess

=item Access => $uAccess

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

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

=item Create => $sCreate

=item Create => $uCreate

C<$sCreate> should be a string constaing zero or one character from
C<"ktn"> and zero or one character from C<"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
C<$uCreate> value.

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

=item Share => $sShare

=item Share => $uShare

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

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

=back

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() } )