ProcTree plugin for Take Command / TCC / TCC/LE
Version 1.1.1 2024-05-08
Charles Dye
Purpose:
This plugin provides two commands and a function to display or return a process’s genealogy.
PROCTREE displays a tree-formatted
list of descendants of a given process. It’s like a cross between
TASKLIST and ENUMPROCESSES.
PROCTREE traces through child processes. It requires an
unbroken line of descent to find descendants. If program A starts program
B, which starts program C and then exits, then PROCTREE cannot
make the connection between A and C. The common link B no longer exists.
This situation is actually not uncommon in Windows. An application might
use a ‘launcher’ program, which checks for available updates
before starting the main program and exiting. Or, an application might
dispense with the separate launcher, check for its own updates, launch a
new instance of itself, and exit. If you find an ‘orphan’
program which is not listed in PROCTREE’s output, this
kind of technique may be the reason.
ANCESTRY is essentially the reverse:
it displays a list of a process’s ancestors. Since each process has
only one parent, the output is not a tree but a simple list, grandparent to
parent to the given process.
@ANCESTRY is ANCESTRY
as a function. It returns a space-separated list of ancestral process IDs.
Installation:
To use this plugin, copy ProcTree.dll to some
known location on your hard drive. (If you are still using the 32-bit version of
Take Command, take ProcTree-x86.dll instead of
ProcTree.dll.) Load the .DLL file with a
PLUGIN /L command, for example:
plugin /l c:\bin\tcmd\test\proctree.dll
If you copy these files to a subdirectory named PlugIns within your Take Command program directory, the plugin will be loaded automatically when TCC starts.
Plugin Features:
New commands: ANCESTRY,
PROCTREE
Syntax Note:
The syntax definitions in the following text use these conventions for clarity:
BOLD CODE | indicates text which must be typed exactly as shown. |
CODE | indicates optional text, which may be typed as shown or omitted. |
| Bold italic | names a required argument; a value must be supplied. |
| Regular italic | names an optional argument. |
| ellipsis… | after an argument means that more than one may be given. |
New Commands:
ANCESTRY — List ancestors of
a given process.
Syntax:
ANCESTRY /C /D /F /H:wild /I /K /M /N:flags /R /T:flags /W:n /X process
/C | show process priorities |
/D | display PIDs in decimal |
/F | show fully-qualified filenames |
/H:wild | highlight matching strings |
/I | show additional info |
/K | show thread counts |
/M | show memory usage |
/N:flags | disable features: CDESWX |
/R | reverse order |
/T:flags | show process creation times: DSMF |
/W:n | specify line width |
/X | display PIDs in hexadecimal (the default) |
| process | the process to start from (process ID or wildspec) |
This command lists the ancestors — the parent, grandparent, etc. — of a process:
- You can enter the process ID in decimal, or hexadecimal with a leading
0x. - You can use wildcards to match the program’s executable name (the name only, not the path), or its window title or service name.
- If you do not specify a starting process, the current shell will be used by default.
Unless you include /R, processes will be listed in chronological
order — oldest to newest, parent before child. The last process
listed will be the one specified on the command line; “self” is
considered the newest “ancestor”.
/C displays the current priority for
each process, using a one- or two-letter abbreviation:
RT | Realtime priority (the highest) |
HI | High priority |
AN | Above normal |
N | Normal priority |
BN | Below normal |
I | Idle (the lowest) |
- | unknown or other |
/F displays a fully-qualified filename
for each process. If ANCESTRY cannot get the filename for a
process, it will fall back on showing a window title or service name instead.
/H:wild
displays process names, window titles, and services names which match the given
wildcard spec in reverse video. You can supply multiple /H: options
to match more than one wildspec. This option has no effect if output is redirected,
or if you disable highlighting with /NC.
/I collects and displays additional
information about each process. If a process is elevated, ANCESTRY
will show an up-arrow ↑ before its name. If it’s
a 32-bit process running under 64-bit Windows, a right guillemet »
will appear before the name.
If you’re still running Windows XP, /I will probably work
only in elevated TCC sessions.
/M shows the amount of memory currently
used by each process, in kilobytes, megabytes, or gigabytes as appropriate.
Fractional units will be rounded to the nearest unit; e.g. 15.7 megabytes
will be shown as ‘16M’.
/N:flags
disables various features. The colon is optional, and you may combine flags
in any order.
C: no highlightD: do not show display names (service names, window titles, full filenames)E: use ASCII periods ‘...’ instead of Unicode ellipses ‘…’ when truncating long stringsS: do not collect service namesW: do not collect window titlesX: do not hide extensions
/NS and /NW are debugging options which prevent
ANCESTRY from gathering service names or window titles. Using
either one will affect wildcard searches; you can’t search for strings
you don’t have. If you don’t want window titles or services
names to be displayed, /ND is the right way to suppress them.
You can get help for this option by typing
ancestry /n?
/T:flags
displays the time each process was started. The colon is optional. You
may include one or more optional flags: D for dates, S
for seconds, M for milliseconds, or F for all of the
above.
You can get help for this option by typing
ancestry /t?
PROCTREE — List descendants of
a given process.
Syntax:
PROCTREE /A /C /D /E /F /H:wild /I /K /M /N:flags /O:keys /P /SVC /TC /T:flags /U /W:n /X /Z root
/A | use ASCII characters |
/C | show process priorities |
/D | display PIDs in decimal |
/E | start from Explorer |
/F | show fully-qualified filenames |
/H:wild | highlight matching strings |
/I | show additional info |
/K | show thread counts |
/M | show memory usage |
/N:flags | disable features: CDESTWX |
/O:keys | sort sibling processes: -CDEKMNPTW |
/P | page output |
/SVC | start from the services root |
/TC | start from Take Command |
/T:flags | show process creation times: DSMF |
/U | include a final summary line |
/W:n | specify line width |
/X | display PIDs in hexadecimal (the default) |
/Z | show the parent of the root process |
| root | the process to start from (process ID or wildspec) |
This command lists the child processes — and grandchildren, great-grandchildren, etc. — of a starting or ‘root’ process. There are several ways to specify the root process:
- You can enter the process ID in decimal, or hexadecimal with a leading
0x. - You can use wildcards to match the program’s executable name (the name only, not the path), or its title or service name.
/Elooks for the root Explorer process./TClooks for Take Command. This only works if you are running in Take Command./SVClooks for services.exe.- If you do not specify a starting process, the current shell will be used by default.
If you specify a nonexistent process ID, PROCTREE will check
whether any current processes claim that PID as a parent. If the process no
longer exists but one or more of its children do, then PROCTREE
will create a ‘dummy’ process entry to use as the root of the
process tree. This dummy process is pure fiction; you cannot display any
meaningful information about it. It’s only there to allow you to list
surviving children of a defunct process.
/A makes PROCTREE use
ASCII characters instead of the fancy Unicode characters. This option might be
useful if you are redirecting or piping PROCTREE’s output.
/A most obviously affects the line-drawing characters used to show
the tree structure, but it has other effects too. It replaces the symbols
used by /I and the ellipses used to
shorten long window titles and service names. Note that even with /A,
there may still be Unicode characters in process names, window titles, and
so on.
/C displays the current priority for
each process, using a one- or two-letter abbreviation:
RT | Realtime priority (the highest) |
HI | High priority |
AN | Above normal |
N | Normal priority |
BN | Below normal |
I | Idle (the lowest) |
- | unknown or other |
/F displays a fully-qualified filename
for each process. If PROCTREE cannot get the filename for a
process, it will fall back on showing a window title or service name instead.
/H:wild
displays process names, window titles, and services names which match the given
wildcard spec in reverse video. You can supply multiple /H: options
to match more than one wildspec. This option has no effect if output is redirected,
or if you disable highlighting with /NC.
/I collects and displays additional
information about each process. If a process is elevated, PROCTREE
will show an up-arrow ↑ before its name. If it’s
a 32-bit process running under 64-bit Windows, a right guillemet »
will appear before the name.
If you’re still running Windows XP, /I will probably work
only in elevated TCC sessions.
/M shows the amount of memory currently
used by each process, in kilobytes, megabytes, or gigabytes as appropriate.
Fractional units will be rounded to the nearest unit; e.g. 15.7 megabytes
will be shown as ‘16M’.
/N:flags
disables various features. The colon is optional, and you may combine flags
in any order.
C: no highlightD: do not show display names (service names, window titles, full filenames)E: use ASCII periods ‘...’ instead of Unicode ellipses ‘…’ when truncating long stringsS: do not collect service namesT: do not display the tree graphicW: do not collect window titlesX: do not hide extensions
/NS and /NW are debugging options which prevent
PROCTREE from gathering service names or window titles. Using
either one will affect /OD and wildcard
searches; you can’t search or sort on strings you don’t have. If
you don’t want window titles or services names to be displayed,
/ND is the right way to suppress them.
You can get help for this option by typing
proctree /n?
/O:keys
tells PROCTREE how to sort sibling processes, i.e.,
processes with the same parent. The colon is optional, and you may give
more than one key.
C: sorts by priority (ascending)D: sorts by display name (service name or window title)E: elevated processes firstK: sorts by thread count (ascending)M: sorts by memory usage (ascending)N: sorts by executable nameP: sorts by process ID (ascending)T: sorts by creation time (oldest first)W: 32-bit processes first-: reverses the following key
Without /O, the default is to sort siblings into ascending
order by process ID.
You can get help for this option by typing
proctree /o?
/T:flags
displays the time each process was started. The colon is optional. You
may include one or more optional flags: D for dates, S
for seconds, M for milliseconds, or F for all of the
above.
You can get help for this option by typing
proctree /t?
/Z displays the parent process ID
for the root process only. (It would be redundant for all the others,
since the tree structure shows this information already.)
New Function:
@ANCESTRY — Returns a list
of ancestors of a given process.
Syntax:
%@ANCESTRY[pid,flags]
| pid | the process ID, in decimal or hexadecimal with a leading 0x |
| flags | bitmapped: |
| 0: return PIDs in hexadecimal (the default) | |
1: return PIDs in hexadecimal, with no leading 0x | |
| 2: return PIDs in decimal | |
| 3: return executable names (note that, unlike process IDs, these may not be unique) | |
| 64: return in reverse order (newest to oldest) | |
| 128: force returned string to lowercase |
If pid is not specified, it defaults to the current shell. By default, processes will be listed in chronological order — oldest to newest, parent before child. The last process ID returned will be the pid originally specified, or the current shell’s. Process IDs will be separated by spaces.
On error (invalid pid?), this function returns an empty string.
Highlight Variable:
The PROCTREE command highlights
executable names when displaying to the console. You can customize this
feature by setting an environment variable Highlight:
rem Disable highlight:
set highlight=none
rem Set the highlight foreground:
set highlight=bright cyan
rem Set both foreground and background:
set highlight=bri whi on blu
rem Numbers are also supported:
set highlight=46
If the Highlight environment variable is not defined, the plugin will
check the registry for a value named Highlight of type REG_SZ.
The plugin will search, in this order:
HKEY_CURRENT_USER\Software\JPPlugins\APingHKEY_CURRENT_USER\Software\JPPlugins
You can also use the /NC option to disable highlighting.
Startup Message:
This plugin displays an informational line when it initializes. The
message will be suppressed in transient or pipe shells. You can disable it
for all shells by defining an environment variable named NOLOADMSG,
for example:
set /e /u noloadmsg=1
Changes:
| Version: | Date: | Changes: |
|---|---|---|
| 1.1.1 | 2024-05-08 | Rewrote ANCESTRY to
recycle much of PROCTREE’s code. Now many PROCTREE
options work in ANCESTRY. |
| 1.1.0 | 2024-05-03 | Added ANCESTRY
and @ANCESTRY. Allow . as a synonym for %_PID. |
| 1.0.5.2 | 2023-10-15 | Tweaked ShowCmdHelp() to include
VER_PATCH. |
| 1.0.5.1 | 2023-10-12 | Updated the plugin’s web address. |
| 1.0.5 | 2023-10-05 | /H:
highlights matching window titles / service names as well as process names.
/HL: is now a synonym for /H: |
| 1.0.4.1 | 2023-10-04 | Formatting change:
/I now uses
a right guillemet instead of an arrowhead to mark 32-bit processes. Added and removed spaces in the
/I info to make things line up a bit better. |
| 1.0.4 | 2023-10-04 | Bug fix: If a process’s alleged parent was started after the process, then your daddy ain’t your daddy (but your daddy don’t know). |
| 1.0.3 | 2022-04-01 | Added /H:
to highlight matching process names. |
| 1.0.2 | 2022-03-28 | Updated the help text and the error messages for
/N /O /T to mention the existence of /N?
/O? /T? |
| 1.0.1 | 2022-03-25 | Replaced _DOSsify() with the more sophisticated FixKernelPath(). |
| 1.0.0 | 2022-03-25 | Added /N? /O?
/T? to give more info on those three options. Removed dependency on
QueryFullProcessImageNameW() in hopes of making the plugin work under Windows XP. |
Status and Licensing:
This plugin is © Copyright 2024, Charles Dye. Unaltered copies of the binary and documentation files may be freely distributed without restriction. I make no guarantee and give no warranty for its operation. If you find a problem, you can report it in the JP Software support forum.
Download:
You can download the current version of the plugin from http://charlesdye.net/dl/proctree.zip.