ProcTree plugin for Take Command / TCC / TCC/LE

Version 1.1.3.1     2024-09-27

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.

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, from the earliest known ancestor to the specified process. @ANCESTRY is ANCESTRY as a function. It returns a space-separated list of ancestral process IDs.

PROCTREE, ANCESTRY, and @ANCESTRY all trace through child processes. They require an unbroken line of descent to find descendants. If program A starts program B, which starts program C and then exits, then PROCTREE et al. 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.

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

New function: @ANCESTRY

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 /L /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
/L	show command lines
/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 highlight
• D: do not show display names (service names, window titles, full filenames)
• E: use ASCII periods ‘...’ instead of Unicode ellipses ‘…’ when truncating long strings
• S: do not collect service names
• W: do not collect window titles
• X: 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 /L /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
/L	show command lines
/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.
• /E looks for the root Explorer process.
• /TC looks for Take Command. This only works if you are running in Take Command.
• /SVC looks 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 highlight
• D: do not show display names (service names, window titles, full filenames)
• E: use ASCII periods ‘...’ instead of Unicode ellipses ‘…’ when truncating long strings
• S: do not collect service names
• T: do not display the tree graphic
• W: do not collect window titles
• X: 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 first
• K: sorts by thread count (ascending)
• M: sorts by memory usage (ascending)
• N: sorts by executable name
• P: 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,sep]

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
sep	separator string

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 unless a different sep string is given.

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\ProcTree
• HKEY_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.3.1	2024-09-27	In decimal mode, PIDs are now left-padded to five characters. ParseInt() now supports octal with a leading 0o. Changed “http://” to “https://’ in the PLUGININFO block.
1.1.3	2024-07-02	Now ANCESTRY pads shorter executable names to make things line up neatly (most of the time). Added an optional separator arg to @ANCESTRY.
1.1.2	2024-06-06	Added /L to display process command lines, as in TASKLIST.
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 https://charlesdye.net/dl/proctree.zip.