/ 
Win32-Process-Info-1.004
River stage zero No dependents
/ Win32::Process::Info

NAME

Win32::Process::Info - Provide process information for Windows 32 systems.

SYNOPSIS

use Win32::Process::Info;
$pi = Win32::Process::Info->new ([machine], [variant]);
$pi->Set (elapsed_as_seconds => 0);	# In clunks, not seconds.
@pids = $pi->ListPids ();	# Get all known PIDs
@info = $pi->GetProcInfo ();	# Get the max
%subs = $pi->Subprocesses ();	# Figure out subprocess relationships.

CAVEAT USER:

This package covers a multitude of sins - as many as Microsoft has invented ways to get process info and I have resources and gumption to code. The key to this mess is the 'variant' argument to the 'new' method (q.v.).

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 (which see) is therefore the most-important method in the package. See it for more information.

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).

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', which means to try WMI first, and NT if WMI fails. 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.

@values = $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.

@values = $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.

@pids = $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.

@info = $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.
%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
WMI -> supported

This method just returns the version number of the Win32::Process::Info object.

ENVIRONMENT

This package is sensitive to a number of environment variables. Note that these are normally consulted only when the package is initialized (i.e. when it's "used" or "required").

PERL_WIN32_PROCESS_INFO_VARIANT

If present, specifies which variant(s) are tried, in which order. The default behaviour is equivalent to specifying 'WMI,NT'. This environment variable is consulted when you "use Win32::Process::Info;". If you want to change it in your Perl code you should use the static Set () method.

PERL_WIN32_PROCESS_INFO_WMI_DEBUG

If present and containing a value Perl recognizes as true, causes the WMI variant to assert the "Debug" privilege. This has the advantage of returning more full paths, but the disadvantage of tending to cause Perl to die when trying to get the owner information on the newly-accessable processes.

PERL_WIN32_PROCESS_INFO_WMI_PARIAH

If present, should contain a semicolon-delimited list of process names for which the package should not attempt to get owner information. '*' is a special case meaning 'all'. You will probably need to use this if you assert PERL_WIN32_PROCESS_INFO_WMI_DEBUG.

REQUIREMENTS

It should be obvious that this library must run under some flavor of Windows.

This library uses the following libraries:

Carp
Time::Local
Win32::API (if using the NT-native variant)
Win32API::Registry (if using the NT-native variant)
Win32::ODBC (if using the WMI variant)

As of ActivePerl 630, none of this uses any packages that are not included with ActivePerl. Your mileage may vary.

HISTORY

0.010 Released as Win32::Process::Info
0.011 Added Version method
      Fixed warning in NT.pm when -w in effect. Fix provided
          by Judy Hawkins (of Pitney Bowes, according to her
          mailing address), and accepted with thanks.
0.012 Hid attributes beginning with "_".
0.013 Use environment variable PERL_WIN32_PROCESS_INFO_VARIANT
          to specify the default variant list.
      Add a hash reference argument to new (); use this to
          specify username and password to the WMI variant.
      Turn on debug privilege in NT variant. This also resulted
          in dependency on Win32API::Registry.
      Return OwnerSid and Owner in NT variant.
0.014 Remove conditional dependencies from Makefile.PL
      Track changes in Win32::API. Can no longer "require" it.
      WMI variant no longer asserts debug privilege by default.
      Use environment variable PERL_WIN32_PROCESS_INFO_WMI_DEBUG
         to tell the WMI variant whether to assert debug.
      Use environment variable PERL_WIN32_PROCESS_INFO_WMI_PARIAH
         to encode processes to skip when determining the owner.
      Add optional first hash ref argument to GetProcInfo.
      Add Subprocesses method.
1.000 Add assert_debug_priv hash argument to the 'new' method.
      Fix documentation, both pod errors and actual doc bugs.
      When the only thing you've done in two months is add a
          semicolon to a comment, it's probably time to call it
          production code.
1.001 Removed dependency on Win32. We still need it, of course,
      but PPM3 chokes on it, and I figure anyone who IS using
      PPM3 already has it, and anyone who ISN'T is smart enough
      to figure out what's going on - or at least read the Readme.
1.002 Document leaky behaviour of WMI variant, and try to make it
      leak less. Document related modules.
1.003 Documented PERL_WIN32_PROCESS_INFO_WMI_DEBUG correctly
      (the docs had a _PRIV on the end).
      Recorded the variant name in the object.
      Clarified (hopefully) the docs on how to use the
      PERL_WIN32_PROCESS_INFO_VARIANT environment variable.
      Added the current status and whereabouts of
      Win32::IProc. Thanks to Eric Bluestein
      (http://www.emblue.com/) for pointing this out.
1.004 Remove commented-out dependencies in Makefile.PL,
      since CPAN's now checking. The only one that really
      counts is Win32, but ActiveState's PPM3 chokes on
      this, or at least did as of January 2001.

BUGS

The WMI variant leaks memory - badly for 1.001 and earlier. After 1.001 it only leaks badly if you retrieve the process owner information. If you're trying to write a daemon, the NT variant is recommended. If you're stuck with WMI, set the no_user_info flag when you call GetProcInfo. This won't stop the leaks, but it minimizes them, at the cost of not returning the username or SID.

RESTRICTIONS

You can not "require" this library except in a BEGIN block. This is a consequence of the use of Win32::API, which has the same restriction, at least in some versions.

RELATED MODULES

Win32::Process::Info focuses on returning static data about a process. If this module doesn't do what you want, maybe one of the following ones will.

Win32::PerfLib by Jutta M. Klebe

This module focuses on performance counters. It is a ".xs" module, and requires Visual C++ 6.0 to install. But it's also part of LibWin32, and should come with ActivePerl.

Win32::IProc by Amine Moulay Ramdane

This module is no longer supported, which is a shame because it returns per-thread information as well. As of December 27, 2004, Jenda Krynicky (http://jenda.krynicky.cz/) was hosting a PPM kit in PPM repository http://jenda.krynicky.cz/perl/, which may be usable. But the source for the DLL files is missing, so if some Windows upgrade breaks it you're out of luck.

Win32API::ProcessStatus, by Ferdinand Prantl

This module focuses on the .exe and .dll files used by the process. It is a ".xs" module, requiring Visual C++ 6.0 and psapi.h to install.

pulist

This is not a Perl module, it's an executable that comes with the NT resource kit.

ACKNOWLEDGMENTS

This module would not exist without the following people:

Aldo Calpini, who gave us Win32::API.

Jenda Krynicky, whose "How2 create a PPM distribution" (http://jenda.krynicky.cz/perl/PPM.html) gave me a leg up on both PPM and tar distributions.

Dave Roth, http://www.roth.net/perl/, author of Win32 Perl Programming: Administrators Handbook, which is published by Macmillan Technical Publishing, ISBN 1-57870-215-1

Dan Sugalski sugalskd@osshe.edu, author of VMS::Process, where I got (for good or ill) the idea of just grabbing all the data I could find on a process and smashing it into a big hash.

The folks of Cygwin (http://www.cygwin.com/), especially Christopher G. Faylor, author of ps.cc.

Judy Hawkins of Pitney Bowes, for providing testing and patches for NT 4.0 without WMI.

AUTHOR

Thomas R. Wyant, III (Thomas.R.Wyant-III@usa.dupont.com)

COPYRIGHT

Copyright 2001, 2002, 2003, 2004 by E. I. DuPont de Nemours and Company, Inc. All rights reserved.

This module is free software; you can use it, redistribute it and/or modify it under the same terms as Perl itself.