view release on metacpan or  search on metacpan

lib/Win32/LongPath.pm  view on Meta::CPAN

=over 4

=item *

B<path separators>: Both the forward (/) and reverse (\) slashes can be used
to separate the path components.

=item *

B<Unicode>: Unicode characters can be used anywhere in the path provided they
are supported by the Windows file naming standard. If Unicode is used, the
string must be internally identified as UTF-8. See L<perlunicode> for more
information on using Unicode with Perl.

=item *

B<drive letter>: The path can begin with an upper or lower case letter from A
to Z followed by a colon to indicate a drive letter path. For example,
C<C:/path> (fullpath) or C<c:path> (relative path).

=item *

B<UNC>: The path can begin with a UNC path in the form C<\\server\share> or
C<//server/share>.

=item *

B<extended-length>: The path can begin with an extended-length prefix in the
form of C<\\?\> or C<//?/>.

=back

All input paths will be converted (I<normalized>) to a fullpath using the
extended-length format and wide characters. This allows paths to be up to
32,767 characters long and to include Unicode characters. The Microsoft
specification still limits the directory component to MAX_PATH (about 255)
characters.

Output paths will be converted back (I<denormalized>) to a UTF-8 fullpath
that begins with a drive letter or UNC.

B<NOTE:> See the I<Naming Files, Paths, and Namespaces> topic in the
L<Microsoft MSDN Library|http://msdn.microsoft.com/library> for more
information about extended-length paths.

=head2 Return Values

Unless stated otherwise, all functions return true (a numeric value of 1)
if successful or false (undef) if an error occurred. Generally, if a
function fails it will set the $! value to the failure. However, $^E will
have the more specific Windows error value.

=head1 FILE FUNCTIONS

This section lists the replacements for native Perl file functions. Since
L</openL> returns a native Perl file handle, functions that use open file
handles (read, write, close, binmode, etc.) can be used as is and do not
have replacement functions. In like manner, L</sysopenL> also returns a
native Perl file handle.

Functions that are specific to the Unix environment (chmod, chown, umask,
etc.) do not have replacements.

=over 4

=item X<linkL>linkL OLDFILE,NEWFILE

If the Windows file system supports it, a hard link is created from
B<NEWFILE> to B<OLDFILE>.

	linkL ('goodbye', 'до свидания')
	  or die ("unable to link file ($^E)");

=item X<lstatL>lstatL PATH

Does the same thing as the L</statL> function but will retrieve the
statistics for the link and not the file it links to.

=item X<openL>openL FILEHANDLEREF,MODE,PATH

open is a very powerful and versatile Perl function with many modes and
capabilities. The openL replacement does not provide the full range of
capability but does provide what is needed to open files in the Windows
file system. It only supports the three-argument form of open.

B<FILEHANDLEREF> cannot be a bareword file handle or a scalar variable.
It must be a reference to a scalar value which will be set to be a Perl
file handle. For example:

	openL (\$fh, '<', $file) or die ("unable to open $file: ($^E)");

For the most part, B<MODE> matches the native definition and can begin
with E<lt>, E<gt>, E<gt>E<gt>, +E<lt>, +E<gt> and +E<gt>E<gt> to
indicate read/write behavior. The E<verbar>-, -E<verbar>, E<lt>-, -,
E<gt>- modes are not valid since they apply to pipes, STDIN and STDOUT.
Read-only is assumed if the read/write symbols are not used. B<MODE>
can also include a colon followed by the I/O layer definition. For
example:

	openL (\$fh, '>:encoding(UTF-8)', $file);

B<PATH> is the relative or fullpath name of the file. It cannot be undef
for temporary files, a reference to a variable for in-memory files or
a file handle.

	# these are WRONG!
	openL ($infh, '', $infile);
	openL (INFILE, '', $infile);
	openL (\$infh, '', undef);
	openL (\$infh, '', \$memory);
	openL (\$infh, '', INFILE);
	openL (\$infh, '-|', "file<$infile");

	# these are correct
	# append infile to outfile
	openL (\$infh, '', $infile)
	  or die ("unable to open $infile: ($^E)");
	openL (\$outfh, '>>', $outfile)
	  or die ("unable to open $outfile: ($^E)");
	while (<$infh>) {
	  print $outfh $_;