NAME

Win32::Process::Info::PT - Provide process information via Proc::ProcessTable.

SYNOPSIS

This package fetches process information on a given machine, using Dan Urist's Proc::ProcessTable. This makes the 'Win32::' part of our name bogus, but lets one use the same basic interface under a wider range of operating systems.

use Win32::Process::Info
$pi = Win32::Process::Info->new (undef, 'PT');
$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::PT 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 package is to get whatever information is convenient (for the author!) about one or more 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 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 PT variant you can hope to get at most the following keys. The caveat is that the Win32::Process::Info keys are derived from Proc::ProcessTable::Process fields, and if your OS does not support the underlying field, you will not get it. Here are the possible keys and the fields from which they are derived:

CreationDate: start
Description: cmndline
ExecutablePath: fname (note 1)
KernelModeTime: stime (note 2)
Name: basename (fname)
Owner: '\' . getpwuid (uid) (note 3)
OwnerSid: uid (note 4)
ParentProcessId: ppid
ProcessId: pid
UserModeTime: utime (note 2)

Notes:

1) ExecutablePath may not be an absolute pathname.

2) We assume that Proc::ProcessTable::Process returns stime and utime in microseconds, and multiply by 10 to get clunks. This may be wrong under some operating systems.

3) Owner has a backslash prefixed because Windows returns domain\user. I don't see a good way to get domain, but I wanted to be consistent (read: I was too lazy to special-case the test script).

4) Note that under Cygwin this is not the same as the Windows PID, which is returned in field 'winpid'. But the Subprocesses method needs the ProcessId and ParentProcessId to be consistent, and there was no documented 'winppid' field.

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. In the case of Win32::Process::Info::PT, this will always be 0, but is provided to be consistent with the other variants.

@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
Proc::ProcessTable

As of this writing, all but Proc::ProcessTable are part of the standard Perl distribution.

ACKNOWLEDGMENTS

This module would not exist without the following people

Dan Urist, author (or at least coordinator) of the Proc::ProcessTable module, upon which this is based.

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.

AUTHOR

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

COPYRIGHT

Copyright 2007, 2009 by Thomas R. Wyant, III. All rights reserved.

LICENSE

This module is free software; you can use it, redistribute it and/or modify it under the same terms as Perl itself. Please see http://perldoc.perl.org/index-licence.html for the current licenses.