Win32(3) Perl Programmers Reference Guide Win32(3)NAMEWin32 - Interfaces to some Win32 API Functions
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
"Win32" module is not part of the Perl source distribu
tion; it is distributed in the libwin32 bundle of Win32::*
modules on CPAN. The module is already preinstalled in
binary distributions like ActivePerl.
Alphabetical Listing of Win32 Functions
Win32::AbortSystemShutdown(MACHINE)
[EXT] Aborts a system shutdown (started by the Initi
ateSystemShutdown function) on the specified MACHINE.
Win32::BuildNumber()
[CORE] Returns the ActivePerl build number. This func
tion is only available in the ActivePerl binary dis
tribution.
Win32::CopyFile(FROM, TO, OVERWRITE)
[CORE] The Win32::CopyFile() function copies an exist
ing file to a new file. All file information like cre
ation time and file attributes will be copied to the
new file. However it will not copy the security infor
mation. 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.
Win32::DomainName()
[CORE] Returns the name of the Microsoft Network
domain that the owner of the current perl process is
logged into. This function does not work on Windows
9x.
Win32::ExpandEnvironmentStrings(STRING)
[EXT] Takes STRING and replaces all referenced envi
ronment variable names with their defined values. Ref
erences to environment variables take the form "%Vari
ableName%". Case is ignored when looking up the Vari
ableName in the environment. If the variable is not
found then the original "%VariableName%" text is
retained. Has the same effect as the following:
$string =~ s/%([^%]*)%/$ENV{$1} || "%$1%"/eg
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 "$^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
Win32::FsType()
[CORE] Returns the name of the filesystem of the cur
rently active drive (like 'FAT' or 'NTFS'). In list
context it returns three values: (FSTYPE, FLAGS, MAX
COMPLEN). 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 compo
nent (the part between two backslashes) on this file
system.
Win32::FreeLibrary(HANDLE)
[EXT] Unloads a previously loaded dynamic-link
library. The HANDLE is no longer valid after this
call. See LoadLibrary for information on dynamically
loading a library.
Win32::GetArchName()
[EXT] Use of this function is deprecated. It is equiv
alent with $ENV{PROCESSOR_ARCHITECTURE}. This might
not work on Win9X.
Win32::GetChipName()
[EXT] Returns the processor type: 386, 486 or 586 for
Intel processors, 21064 for the Alpha chip.
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.
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::Get
LongPathName.
This function has been added for Perl 5.6.
Win32::GetLastError()
[CORE] Returns the last error value generated by a
call to a Win32 API function. Note that "$^E" used in
a numeric context amounts to the same value.
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. Com
pare with Win32::GetShortPathName and Win32::GetFull
PathName.
This function has been added for Perl 5.6.
Win32::GetNextAvailDrive()
[CORE] Returns a string in the form of "<d>:" where
<d> is the first available drive letter.
Win32::GetOSVersion()
[CORE] Returns the array (STRING, MAJOR, MINOR, BUILD,
ID), where the elements are, respectively: An arbi
trary descriptive string, the major version number of
the operating system, the minor version number, the
build number, and a digit indicating the actual oper
ating 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.
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::GetLongPath
Name.
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.
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).
Win32::InitiateSystemShutdown
(MACHINE, MESSAGE, TIMEOUT, FORCECLOSE, REBOOT)
[EXT] Shutsdown the specified MACHINE, notifying users
with the supplied MESSAGE, within the specified TIME
OUT 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.
Win32::IsWinNT()
[CORE] Returns non zero if the Win32 subsystem is Win
dows NT.
Win32::IsWin95()
[CORE] Returns non zero if the Win32 subsystem is
Windows 95.
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.
Win32::LoginName()
[CORE] Returns the username of the owner of the cur
rent perl process.
Win32::LookupAccountName(SYSTEM, ACCOUNT, DOMAIN, SID,
SIDTYPE)
[EXT] Looks up ACCOUNT on SYSTEM and returns the
domain name the SID and the SID type.
Win32::LookupAccountSID(SYSTEM, SID, ACCOUNT, DOMAIN, SID
TYPE)
[EXT] Looks up SID on SYSTEM and returns the account
name, domain name, and the SID type.
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
Win32::NodeName()
[CORE] Returns the Microsoft Network node-name of the
current machine.
Win32::RegisterServer(LIBRARYNAME)
[EXT] Loads the DLL LIBRARYNAME and calls the function
DllRegisterServer.
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.
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.
Win32::Sleep(TIME)
[CORE] Pauses for TIME milliseconds. The timeslices
are made available to other processes and threads.
Win32::Spawn(COMMAND, ARGS, PID)
[CORE] Spawns a new process using the supplied COM
MAND, 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.
Win32::UnregisterServer(LIBRARYNAME)
[EXT] Loads the DLL LIBRARYNAME and calls the function
DllUnregisterServer.
2001-02-22 perl v5.6.1 Win32(3)
