Description :
The main purpose of the Win32::Process::Info package is to get whatever
information is convenient (for the author!) about one or more Windows 32
processes. GetProcInfo is therefore the most-important method in the
package. See it for more information.
The process IDs made available are those returned by the variant in use.
See the documentation to the individual variants for details, especially if
you are a Cygwin user.
Unless explicitly stated otherwise, modules, variables, and so on are
considered private. That is, the author reserves the right to make
arbitrary changes in the way they work, without telling anyone. For
methods, variables, and so on which are considered public, the author will
make an effort keep them stable, and failing that to call attention to
changes.
The following methods should be considered public:
* $pi = Win32::Process::Info->new ([machine], [variant], [hash])
This method instantiates a process information object, connected to the
given machine, and using the given variant.
The following variants are currently supported:
NT - Uses the NT-native mechanism. Good on any NT, including Windows 2000.
This variant does not support connecting to another machine, so the
\'machine\' argument must be an empty string (or undef, if you prefer).
PT - Uses Dan Urist\'s Proc::ProcessTable, making it possible
(paradoxically) to use this module on other operating systems than Windows.
Only those Proc::ProcessTable::Process fields which seem to correspond to
WMI items are returned. *Caveat:* the PT variant is to be considered
experimental, and may be changed or retracted in future releases.
WMI - Uses the Windows Management Implementation. Good on Win2K, ME, and
possibly others, depending on their vintage and whether WMI has been
retrofitted.
The initial default variant comes from environment variable
PERL_WIN32_PROCESS_INFO_VARIANT. If this is not found, it will be
\'WMI,NT,PT\', which means to try WMI first, NT if WMI fails, and PT as a
last resort. This can be changed using Win32::Process::Info->Set (variant
=> whatever).
The hash argument is a hash reference to additional arguments, if any. The
hash reference can actually appear anywhere in the argument list, though
positional arguments are illegal after the hash reference.
The following hash keys are supported:
variant => corresponds to the \'variant\' argument (all)
assert_debug_priv => assert debug if available (all) This
only has effect under WMI. The NT variant always
asserts debug. You want to be careful doing this
under WMI if you\'re fetching the process owner
information, since the script can be badly behaved
(i.e. die horribly) for those processes whose
ExecutablePath is only available with the debug
privilege turned on.
host => corresponds to the \'machine\' argument (WMI)
user => username to perform operation under (WMI)
password => password corresponding to the given
username (WMI)
ALL hash keys are optional. SOME hash keys are only supported under certain
variants. These are indicated in parentheses after the description of the
key. It is an error to specify a key that the variant in use does not
support.
* AATTvalues = $pi->Get (attributes ...)
This method returns the values of the listed attributes. If called in
scalar context, it returns the value of the first attribute specified, or
undef if none was. An exception is raised if you specify a non-existent
attribute.
This method can also be called as a class method (that is, as
Win32::Process::Info->Get ()) to return default attributes values.
The relevant attribute names are:
*elapsed_as_seconds* is TRUE to convert elapsed user and kernel times to
seconds. If FALSE, they are returned in clunks (that is, hundreds of
nanoseconds). The default is TRUE.
*variant* is the variant of the Process::Info code in use, and should be
zero or more of \'WMI\' or \'NT\', separated by commas. \'WMI\' selects the
Windows Management Implementation, and \'NT\' selects the Windows NT native
interface.
*machine* is the name of the machine connected to. This is not available as
a class attribute.
* AATTvalues = $pi->Set (attribute => value ...)
This method sets the values of the listed attributes, returning the values
of all attributes listed if called in list context, or of the first
attribute listed if called in scalar context.
This method can also be called as a class method (that is, as
Win32::Process::Info->Set ()) to change default attribute values.
The relevant attribute names are the same as for Get. However:
*variant* is read-only at the instance level. That is,
Win32::Process::Info->Set (variant => \'NT\') is OK, but $pi->Set (variant =>
\'NT\') will raise an exception. If you set *variant* to an empty string (the
default), the next \"new\" will iterate over all possibilities (or the
contents of environment variable PERL_WIN32_PROCESS_INFO_VARIANT if
present), and set *variant* to the first one that actually works.
*machine* is not available as a class attribute, and is read-only as an
instance attribute. It is *not* useful for discovering your machine name -
if you instantiated the object without specifying a machine name, you will
get nothing useful back.
* AATTpids = $pi->ListPids ();
This method lists all known process IDs in the system. If called in scalar
context, it returns a reference to the list of PIDs. If you pass in a list
of pids, the return will be the intersection of the argument list and the
actual PIDs in the system.
* AATTinfo = $pi->GetProcInfo ();
This method returns a list of anonymous hashes, each containing information
on one process. If no arguments are passed, the list represents all
processes in the system. You can pass a list of process IDs, and get out a
list of the attributes of all such processes that actually exist. If you
call this method in scalar context, you get a reference to the list.
What keys are available depends on the variant in use. You can hope to get
at least the following keys for a \"normal\" process (i.e. not the idle
process, which is PID 0, nor the system, which is some small indeterminate
PID) to which you have access:
CreationDate
ExecutablePath
KernelModeTime
MaximumWorkingSetSize
MinimumWorkingSetSize
Name (generally the name of the executable file)
ProcessId
UserModeTime
You may find other keys available as well, depending on which operating
system you\'re using, and which variant of Process::Info you\'re using.
This method also optionally takes as its first argument a reference to a
hash of option values. The only supported key is:
no_user_info => 1
Do not return keys Owner and OwnerSid, even if available.
These tend to be time-consuming, and can cause problems
under the WMI variant.
* Win32::Process::Info->import ()
The purpose of this static method is to specify which variants of the
functionality are legal to use. Possible arguments are \'NT\', \'WMI\', \'PT\',
or some combination of these (e.g. (\'NT\', \'WMI\')). Unrecognized arguments
are ignored, though this may change if this class becomes a subclass of
Exporter. If called with no arguments, it is as though it were called with
arguments (\'NT\', \'WMI\', \'PT\'). See BUGS, below, for why this mess was
introduced in the first place.
This method must be called at least once, *in a BEGIN block*, or *no*
variants will be legal to use. Usually it does *not* need to be explicitly
called by the user, since it is called implicitly when you \'use
Win32::Process::Info;\'. If you \'require Win32::Process::Info;\' you *will*
have to call this method explicitly.
If this method is called more than once, the second and subsequent calls
will have no effect on what variants are available. The reason for this
will be made clear (I hope!) under USE IN OTHER MODULES, below.
The only time a user of this module needs to do anything different versus
version 1.006 and previous of this module is if this module is being loaded
in such a way that this method is not implicitly called. This can happen
two ways:
use Win32::Process::Info ();
explicitly bypasses the implicit call of this method. Don\'t do that.
require Win32::Process::Info;
also does not call this method. If you must load this module using require
rather than use, follow the require with
Win32::Process::Info->import ();
passing any necessary arguments.
* %subs = $pi->Subprocesses ([pid ...])
This method takes as its argument a list of PIDs, and returns a hash
indexed by PID and containing, for each PID, a reference to a list of all
subprocesses of that process. If those processes have subprocesses as well,
you will get the sub-sub processes, and so ad infinitum, so you may well
get back more hash keys than you passed process IDs. Note that the process
of finding the sub-sub processes is iterative, not recursive; so you don\'t
get back a tree.
If no argument is passed, you get all processes in the system.
If called in scalar context you get a reference to the hash.
This method works off the ParentProcessId attribute. Not all variants
support this. If the variant you\'re using doesn\'t support this attribute,
you get back an empty hash. Specifically:
NT -> unsupported
PT -> supported
WMI -> supported
* AATTinfo = $pi->SubProcInfo ();
This is a convenience method which wraps GetProcInfo(). It has the same
calling sequence, and returns generally the same data. But the data
returned by this method will also have the {subProcesses} key, which will
contain a reference to an array of hash references representing the data on
subprocesses of each process.
Unlike the data returned from Subprocesses(), the data here are not
flattened; so if you specify one or more process IDs as arguments, you will
get back at most the number of process IDs you specified; fewer if some of
the specified processes do not exist.
*Note well* that a given process can occur more than once in the output. If
you call SubProcInfo without arguments, the AATTinfo array will contain every
process in the system, even those which are also in some other process\'
{subProcesses} array.
Also unlike Subprocesses(), you will get an exception if you use this
method with a variant that does not support the ParentProcessId key.
* $pid = $pi->My_Pid()
This convenience method returns the process ID of the current process, in a
form appropriate to the operating system and the variant in use. Normally,
it simply returns \'$$\'. But Cygwin has its own idea of what the process ID
is, which may differ from Windows. Worse than that, under Cygwin the NT and
WMI variants return Windows PIDs, while PT appears to return Cygwin PIDs.
* $text = Win32::Process::Info->variant_support_status($variant);
This static method returns the support status of the given variant. The
return is false if the variant is supported, or an appropriate message if
the variant is unsupported.
This method can also be called as a normal method, or even as a subroutine.
* print \"$pi Version = AATT{[$pi->Version ()]}\
\"
This method just returns the version number of the Win32::Process::Info
object.
|
