Win32::Process::Info::NT - Provide process information via NT-native calls.

NAME

Win32::Process::Info::NT - Provide process information via NT-native calls.

SYNOPSIS

This package fetches process information on a given Windows machine, using Microsoft Windows NT's native process information calls.

 use Win32::Process::Info
 $pi = Win32::Process::Info->new (undef, 'NT');
 $pi->Set (elapsed_as_seconds => 0);    # In clunks, not seconds.
 @pids = $pi->ListPids ();      # Get all known PIDs
 @info = $pi->GetProcInfo ();   # Get the max

CAVEAT USER:

This package does not support access to a remote machine, because the underlying API doesn't. If you specify a machine name (other than '', 0, or undef) when you instantiate a new Win32::Process::Info::NT object, you will get an exception.

This package is not intended to be used independently; instead, it is a subclass of Win32::Process::Info, and should only be called via that package.

DESCRIPTION

The main purpose of the Win32::Process::Info::NT 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 subroutine in the package. See it for more information.

This package returns Windows process IDs, even under Cygwin.

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 subroutines, 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.

Nothing is exported by default, though all the public subroutines are exportable, either by name or by using the :all tag.

The following subroutines should be considered public:

@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 depend on the variant in use. With the NT variant 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 _usually_ PID 8) to which you have access:

    CreationDate
    ExecutablePath
    KernelModeTime
    MaximumWorkingSetSize
    MinimumWorkingSetSize
    Name (generally the name of the executable file)
    OtherOperationCount
    OtherTransferCount (= number of bytes transferred)
    ProcessId
    ReadOperationCount
    ReadTransferCount (= number of bytes read)
    UserModeTime
    WriteOperationCount
    WriteTransferCount (= number of bytes read)

All returns are Perl scalars. The I/O statistic keys represent counts if named *OperationCount, or bytes if named *TransferCount.

Note that:

- The I/O statistic keys will only be present on Windows 2000.

- The MinimumWorkingSetSize and MaximumWorkingSetSize keys have no apparent relationship to the amount of memory actually consumed by the process.

The output will contain all processes for which information was requested, but will not necessarily contain all information for all processes.

The _status key of the process hash contains the status of GetProcInfo's request(s) for information. If all information is present, the status element of the hash will be zero. If there was any problem getting any of the information, the _status element will contain the Windows error code ($^E + 0, to be precise). You might want to look at it - or not count on the hashes being fully populated (or both!).

Note that GetProcInfo is not, at the moment, able to duplicate the information returned by the resource kit tool pulist.exe. And it may never do so. Pulist.exe relies on the so-called internal APIs, which for NT are found in ntdll.dll, which may not be linked against. Pulist.exe gets around this by loading it at run time, and calling NtQuerySystemInformation. The required constants and structure definitions are in Winternl.h, which doesn't come with VCC. The caveat at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ devnotes/winprog/calling_internal_apis.asp claims that they reserve the right to change this without notice, so I hesitate to program against it. Sorry. I guess the real purpose of this paragraph is to say that I _did_ try.

@pids = $pi->ListPids ()

This subroutine returns a list of all known process IDs in the system, in no particular order. If called in list context, the list of process IDs itself is returned. In scalar context, a reference to the list is returned.

REQUIREMENTS

This library uses the following libraries:

 Carp
 Time::Local
 Win32
 Win32::API
 Win32API::Registry (if available)

As of this writing, all but Win32 and Win32::API are part of the standard Perl distribution. Win32 is not part of the standard Perl distribution, but comes with the ActivePerl distribution. Win32::API comes with ActivePerl as of about build 630, but did not come with earlier versions. It must be installed before installing this module.

ACKNOWLEDGMENTS

This module would not exist without the following people:

Aldo Calpini, who gave us Win32::API.

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

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.

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

AUTHOR

Thomas R. Wyant, III (wyant at cpan dot org)

COPYRIGHT AND LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses in the directory LICENSES.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

Win32::Process::Info::NT - Provide process information via NT-native calls.