integrate cfgperl changes#6293..6324 into mainline

p4raw-link: @6324 on //depot/cfgperl: 81bf48a6dbba4b295dfa172a17ca70b654dbf225
p4raw-link: @6293 on //depot/cfgperl: 6e37ea6052902cde1aeb08a2129ffc7c8ea53736

p4raw-id: //depot/perl@6369
p4raw-branched: from //depot/cfgperl@6368 'branch in' lib/Win32.pod
	lib/lib_pm.PL
p4raw-deleted: from //depot/cfgperl@6368 'delete in' pod/Win32.pod
	(@5937..) pod/buildtoc (@6091..) lib/lib.pm.PL (@6227..)
	pod/Makefile (@6232..)
p4raw-integrated: from //depot/cfgperl@6368 'copy in' thread.h
	(@5656..) lib/warnings/register.pm (@5704..) ext/B/B/Stash.pm
	(@5972..) lib/CGI/Util.pm (@6034..) util.c (@6217..) gv.c
	(@6244..) pp.c (@6260..) doop.c (@6269..) pod/perlfunc.pod
	(@6277..) pp_ctl.c (@6293..) makedef.pl (@6301..) embed.h
	global.sym objXSUB.h perlapi.c proto.h (@6305..) win32/Makefile
	(@6307..) Makefile.SH (@6309..) t/op/method.t (@6312..) sv.h
	(@6315..) 'ignore' op.c (@6273..) 'merge in' embed.pl
	win32/win32.c (@6305..)
p4raw-integrated: from //depot/cfgperl@6324 'merge in' toke.c (@6307..)
p4raw-branched: from //depot/cfgperl@6323 'branch in' pod/buildtoc.PL
	(@6319..)
p4raw-integrated: from //depot/cfgperl@6323 'copy in' pod/perl.pod
	(@6319..) pod/perltoc.pod (@6322..) 'merge in' MANIFEST
	(@6319..)
p4raw-branched: from //depot/cfgperl@6319 'branch in' pod/Makefile.SH
p4raw-integrated: from //depot/cfgperl@6315 'ignore' pp_hot.c (@6313..)
p4raw-integrated: from //depot/cfgperl@6311 'copy in'
	ext/POSIX/POSIX.pod (@6296..)
p4raw-integrated: from //depot/cfgperl@6307 'merge in' doio.c (@6223..)

1 files changed, 284 insertions, 0 deletions

diff --git a/lib/Win32.pod b/lib/Win32.pod
new file mode 100644
index 0000000000..bd1d06581e
--- /dev/null
+++ b/lib/Win32.pod
@@ -0,0 +1,284 @@
+=head1 NAME
+
+Win32 - Interfaces to some Win32 API Functions
+
+=head1 DESCRIPTION
+
+Perl on Win32 contains several functions to access Win32 APIs. Some
+are included in Perl itself (on Win32) and some are only available
+after explicitly requesting the Win32 module with:
+
+	use Win32;
+
+The builtin functions are marked as [CORE] and the other ones
+as [EXT] in the following alphabetical listing. The C<Win32> module
+is not part of the Perl source distribution; it is distributed in
+the libwin32 bundle of Win32::* modules on CPAN. The module is
+already preinstalled in binary distributions like ActivePerl.
+
+=head2 Alphabetical Listing of Win32 Functions
+
+=over
+
+=item Win32::AbortSystemShutdown(MACHINE)
+
+[EXT] Aborts a system shutdown (started by the
+InitiateSystemShutdown function) on the specified MACHINE.
+
+=item Win32::BuildNumber()
+
+[CORE] Returns the ActivePerl build number. This function is
+only available in the ActivePerl binary distribution.
+
+=item Win32::CopyFile(FROM, TO, OVERWRITE)
+
+[CORE] The Win32::CopyFile() function copies an existing file to a new
+file. All file information like creation time and file attributes will
+be copied to the new file. However it will B<not> copy the security
+information. If the destination file already exists it will only be
+overwritten when the OVERWRITE parameter is true. But even this will
+not overwrite a read-only file; you have to unlink() it first
+yourself.
+
+=item Win32::DomainName()
+
+[CORE] Returns the name of the Microsoft Network domain that the
+owner of the current perl process is logged into.
+
+=item Win32::ExpandEnvironmentStrings(STRING)
+
+[EXT] Takes STRING and replaces all referenced environment variable
+names with their defined values. References to environment variables
+take the form C<%VariableName%>. Case is ignored when looking up the
+VariableName in the environment. If the variable is not found then the
+original C<%VariableName%> text is retained.  Has the same effect
+as the following:
+
+	$string =~ s/%([^%]*)%/$ENV{$1} || "%$1%"/eg
+
+=item Win32::FormatMessage(ERRORCODE)
+
+[CORE] Converts the supplied Win32 error number (e.g. returned by
+Win32::GetLastError()) to a descriptive string.  Analogous to the
+perror() standard-C library function.  Note that C<$^E> used
+in a string context has much the same effect.
+
+	C:\> perl -e "$^E = 26; print $^E;"
+	The specified disk or diskette cannot be accessed
+
+=item Win32::FsType()
+
+[CORE] Returns the name of the filesystem of the currently active
+drive (like 'FAT' or 'NTFS'). In list context it returns three values:
+(FSTYPE, FLAGS, MAXCOMPLEN). FSTYPE is the filesystem type as
+before. FLAGS is a combination of values of the following table:
+
+	0x00000001  supports case-sensitive filenames
+	0x00000002  preserves the case of filenames
+	0x00000004  supports Unicode in filenames
+	0x00000008  preserves and enforces ACLs
+	0x00000010  supports file-based compression
+	0x00000020  supports disk quotas
+	0x00000040  supports sparse files
+	0x00000080  supports reparse points
+	0x00000100  supports remote storage
+	0x00008000  is a compressed volume (e.g. DoubleSpace)
+	0x00010000  supports object identifiers
+	0x00020000  supports the Encrypted File System (EFS)
+
+MAXCOMPLEN is the maximum length of a filename component (the part
+between two backslashes) on this file system.
+
+=item Win32::FreeLibrary(HANDLE)
+
+[EXT] Unloads a previously loaded dynamic-link library. The HANDLE is
+no longer valid after this call. See L<LoadLibrary|Win32::LoadLibrary(LIBNAME)>
+for information on dynamically loading a library.
+
+=item Win32::GetArchName()
+
+[EXT] Use of this function is deprecated. It is equivalent with
+$ENV{PROCESSOR_ARCHITECTURE}. This might not work on Win9X.
+
+=item Win32::GetChipName()
+
+[EXT] Returns the processor type: 386, 486 or 586 for Intel processors,
+21064 for the Alpha chip.
+
+=item Win32::GetCwd()
+
+[CORE] Returns the current active drive and directory. This function
+does not return a UNC path, since the functionality required for such
+a feature is not available under Windows 95.
+
+=item Win32::GetFullPathName(FILENAME)
+
+[CORE] GetFullPathName combines the FILENAME with the current drive
+and directory name and returns a fully qualified (aka, absolute)
+path name. In list context it returns two elements: (PATH, FILE) where
+PATH is the complete pathname component (including trailing backslash)
+and FILE is just the filename part.  Note that no attempt is made to
+convert 8.3 components in the supplied FILENAME to longnames or
+vice-versa.  Compare with Win32::GetShortPathName and
+Win32::GetLongPathName.  
+
+This function has been added for Perl 5.6.
+
+=item Win32::GetLastError()
+
+[CORE] Returns the last error value generated by a call to a Win32 API
+function.  Note that C<$^E> used in a numeric context amounts to the
+same value.
+
+=item Win32::GetLongPathName(PATHNAME)
+
+[CORE] Returns a representation of PATHNAME composed of longname
+components (if any).  The result may not necessarily be longer
+than PATHNAME.  No attempt is made to convert PATHNAME to the
+absolute path.  Compare with Win32::GetShortPathName and
+Win32::GetFullPathName.
+
+This function has been added for Perl 5.6.
+
+=item Win32::GetNextAvailDrive()
+
+[CORE] Returns a string in the form of "<d>:" where <d> is the first
+available drive letter.
+
+=item Win32::GetOSVersion()
+
+[CORE] Returns the array (STRING, MAJOR, MINOR, BUILD, ID), where
+the elements are, respectively: An arbitrary descriptive string, the
+major version number of the operating system, the minor version
+number, the build number, and a digit indicating the actual operating
+system. For ID, the values are 0 for Win32s, 1 for Windows 9X and 2
+for Windows NT. In scalar context it returns just the ID.
+
+=item Win32::GetShortPathName(PATHNAME)
+
+[CORE] Returns a representation of PATHNAME composed only of
+short (8.3) path components.  The result may not necessarily be
+shorter than PATHNAME.  Compare with Win32::GetFullPathName and
+Win32::GetLongPathName.
+
+=item Win32::GetProcAddress(INSTANCE, PROCNAME)
+
+[EXT] Returns the address of a function inside a loaded library. The
+information about what you can do with this address has been lost in
+the mist of time. Use the Win32::API module instead of this deprecated
+function.
+
+=item Win32::GetTickCount()
+
+[CORE] Returns the number of milliseconds elapsed since the last
+system boot. Resolution is limited to system timer ticks (about 10ms
+on WinNT and 55ms on Win9X).
+
+=item Win32::InitiateSystemShutdown(MACHINE, MESSAGE, TIMEOUT, FORCECLOSE, REBOOT)
+
+[EXT] Shutsdown the specified MACHINE, notifying users with the
+supplied MESSAGE, within the specified TIMEOUT interval. Forces
+closing of all documents without prompting the user if FORCECLOSE is
+true, and reboots the machine if REBOOT is true. This function works
+only on WinNT.
+
+=item Win32::IsWinNT()
+
+[CORE] Returns non zero if the Win32 subsystem is Windows NT.
+
+=item Win32::IsWin95()
+
+[CORE] Returns non zero if the Win32 subsystem is Windows 95.
+
+=item Win32::LoadLibrary(LIBNAME)
+
+[EXT] Loads a dynamic link library into memory and returns its module
+handle. This handle can be used with Win32::GetProcAddress and
+Win32::FreeLibrary. This function is deprecated. Use the Win32::API
+module instead.
+
+=item Win32::LoginName()
+
+[CORE] Returns the username of the owner of the current perl process.
+
+=item Win32::LookupAccountName(SYSTEM, ACCOUNT, DOMAIN, SID, SIDTYPE)
+
+[EXT] Looks up ACCOUNT on SYSTEM and returns the domain name the SID and
+the SID type.
+
+=item Win32::LookupAccountSID(SYSTEM, SID, ACCOUNT, DOMAIN, SIDTYPE)
+
+[EXT] Looks up SID on SYSTEM and returns the account name, domain name,
+and the SID type.
+
+=item Win32::MsgBox(MESSAGE [, FLAGS [, TITLE]])
+
+[EXT] Create a dialogbox containing MESSAGE. FLAGS specifies the
+required icon and buttons according to the following table:
+
+	0 = OK
+	1 = OK and Cancel
+	2 = Abort, Retry, and Ignore
+	3 = Yes, No and Cancel
+	4 = Yes and No
+	5 = Retry and Cancel
+
+	MB_ICONSTOP          "X" in a red circle
+	MB_ICONQUESTION      question mark in a bubble
+	MB_ICONEXCLAMATION   exclamation mark in a yellow triangle
+	MB_ICONINFORMATION   "i" in a bubble
+
+TITLE specifies an optional window title. The default is "Perl".
+
+The function returns the menu id of the selected push button:
+
+	0  Error
+
+	1  OK
+	2  Cancel
+	3  Abort
+	4  Retry
+	5  Ignore
+	6  Yes
+	7  No
+
+=item Win32::NodeName()
+
+[CORE] Returns the Microsoft Network node-name of the current machine.
+
+=item Win32::RegisterServer(LIBRARYNAME)
+
+[EXT] Loads the DLL LIBRARYNAME and calls the function DllRegisterServer.
+
+=item Win32::SetCwd(NEWDIRECTORY)
+
+[CORE] Sets the current active drive and directory. This function does not
+work with UNC paths, since the functionality required to required for
+such a feature is not available under Windows 95.
+
+=item Win32::SetLastError(ERROR)
+
+[CORE] Sets the value of the last error encountered to ERROR. This is
+that value that will be returned by the Win32::GetLastError()
+function. This functions has been added for Perl 5.6.
+
+=item Win32::Sleep(TIME)
+
+[CORE] Pauses for TIME milliseconds. The timeslices are made available
+to other processes and threads.
+
+=item Win32::Spawn(COMMAND, ARGS, PID)
+
+[CORE] Spawns a new process using the supplied COMMAND, passing in
+arguments in the string ARGS. The pid of the new process is stored in
+PID. This function is deprecated. Please use the Win32::Process module
+instead.
+
+=item Win32::UnregisterServer(LIBRARYNAME)
+
+[EXT] Loads the DLL LIBRARYNAME and calls the function
+DllUnregisterServer.
+
+=back
+
+=cut