SUT Home
Project Status Download Papers Documentation License Mailing List Propaganda Old Website Links

ptfps

SUT find in process space

Description

ptfps finds processes on multiple machines based on an expression which is evaluated for each process on each machine. ptfps is best thought of as a cross between ps and find.

Command Line Arguments

ptfps [-m <machine_file>|-M <machine_list>] <expression>

-m <machine_file>: Specify a file with a list of destination machines. It is incorrect to use this with the -M option. This option must preceed all others.
-M <machine_list>: Specify a list of destination machines. The entire list must be surrounded by quotes. It is incorrect to use this with the -m option. This option must preceed all others.
<expression>: Any valid expression. All processes that ptfps finds on the given machines will be evaluated against this expression. See section "Expressions" below.

Expressions

An expression is composed of terms and conjunctions. An expression may also be empty, meaning true for all processes. See "Examples" below.

Test terms

Test terms are terms where some sort of validation is made on a process.

-cmd <command>: Evaluates to true on processes whose executable name matches the given command name.
-egid <gid1>[,gid2[,gid3...]]: Evaluates to true when the effective GID (group id) of a process matches the given gids.
-euid <uid1>[,uid2[,uid3...]]: Evaluates to true when the effective UID (user id) of a process matches the given uids.
-false: Always evaluates to false
-gid <gid1>[,gid2[,gid3...]]: Evaluates to true when the effective GID (group id) of a process matches any of the given gids
-group <group1>[,group2[,group3...]]: Evaluates to true when the effective group name of a process matches any of the given group names.
-name <name1>[,name2[,name3]]: Evaluates to true when the name of a process matches any of the given process names. In this case, the name of a process refers to the executable name as well as the initial few arguments of the process.
-nice <nicelvl>: Evaluates to true when the nice value of a process is greater than or equal to niceval (numerically).
-pcpu <percentage>: Evaluates to true on processes that have used the CPU (as a percentage of its total running time) more than the given percentage.
-pid <pid1>[,pid2[,pid3...]]: Evaluates to true when the PID (process id) of a process matches any of the given pids.
-pmem <percentage>: Evaluates to true on processes that are using more memory (as a percentage of total system memory on the host of the process) than the given percentage.
-ppid <ppid1>[,ppid2[,ppid3...]]: Evaluates to true when the parent PID(process id) of a process matches any of the given pids.
-pri <pri>: Evaluates to true when the priority of a process is greater than or equal to pri (numerically).
-rgid <gid1>[,gid2[,gid3...]]: Evaluates to true when the real GID (group id) of a process matches the given gids.
-ruid <uid1>[,uid2[,uid3...]]: Evaluates to true when the real UID (user id) of a process matches the given uids.
-runnable: Evaluates to true when a process is runnable.
-sgid <gid1>[,gid2[,gid3...]]: Evaluates to true when the saved GID (group id) of a process matches the given gids.
-sleeping: Evaluates to true when a process is sleeping (swapped on AIX).
-stime <date>: Evaluates to true on processes whose start time is later than the given date.
-stopped: Evaluates to true when a process is stopped or traced.
-suid <uid1>[,uid2[,uid3...]]: Evaluates to true when the saved UID (user id) of a process matches the given uids.
-time <seconds>: Evaluates to true on processes that have used more CPU time than the given number of seconds.
-traced: Evaluates to true when a process is stopped or traced.
-true: Always evaluates to true
-tty <tty1>[,tty2[,tty3]]: Evaluates to true when the tty name of a process matches any of the given tty names.
-uid <uid1>[,uid2[,uid3...]]: Evaluates to true when the effective UID (user id) of a process matches the given uids.
-user <user1>[,user2[,user3...]]: Evaluates to true when the effective user name of a process matches any of the given usernames.
-zombie: Evaluates to true when a process is a zombie (it has exited, but its parent has not called wait).

Action terms

Action terms are terms that perform some action. No tests are performed.

-exec <command> [arguments] ;: Executes the given command and returns true if command has a zero exit status and false otherwise. If "{}" appears in the argument list, it is replaced by the process id of the process. This occurs in all such instances. Note that it may be necessary to "escape" the semicolon and/or the french braces on some shells.
-kill <signal>: Sends the given signal to the process and if it succeeds, evaluates to true, otherwise evaluates to false.
-print <format>: Always evaluates to true and prints the given process in the given format. The format can be NORMAL, LONG, FULL, or BSDu. NORMAL is the format used by ps when no other format specifiers are given. LONG is the long format from the BSD versions of ps. FULL is the full format used by SysV versions of ps. BSDu is the "u" format used by BSD versions of ps. "-print NORMAL" is implied if no other action command is GIVEN (i.e. the expression given on the command line is -and'ed with "-print NORMAL", with print appearing on the right hand side).

Operators

Conjunction operators

Conjunctions are logical joiners between terms. Note that all "AND" conjunctions have higher precidence than all "OR" terms. See examples below.

<expression> -and <expression>: this type of expression evaluates to true only if both the expression to the left and the expression to the right of "-and" evaluate to true on the process. If the left expression is false, the right expression is not evaluated.
<expression> -a <expression>: same as -and.
<expression> <expression>: same as -and (implied and).
<expression> -or <expression>: this type of expression evaluates to true if either the expression to the left or the expression to the right of "-or" evaluate to true on the process. If the left expression is true, the right expression is not evaluated.
<expression> -o <expression>: same as -or.

Negation operators

-not <expression>: this operation negates the result of the expression to which it is applied.
! <expression>: same as -not.

Grouping operators

( <expression> ): this operation forces the enclosed expression to be evaluated without regard to precidence rules between operators inside and outside the parentheses. Note that many shells require the "(" and ")" symbols to be quoted. See examples below.

Examples

To view all processes on the machines listed in the file "destination_machines" use

ptfps -m destination_machines

To view all processes on the hosts host1, host2, and host3, use

ptfps -M "host1 host2 host3"

Similarly, an abbreviation may be used:

ptfps -M "host%d@1-3"

where the %d is replaced by the numbers 1-3 by ptfps.

To view all processes owned by user johndoe and janedoe that have parent pid 1 on the hosts listed in destination_machines, use

ptfps -m destination_machines -users johndoe,janedoe -ppid 1

Note that in this example, there is an implicit "-and" between the terms "-users johndoe,janedoe" and "-ppid 1". Also note that if this system uses regular expressions, the usernames will match with any username with "johndoe" or "janedoe" as a substring (e.g. both the usernames "johndoe" and "johndoel" will be matched). To match all processes by "johndoe" or "janedoe" only (with parent pid 1), use the regular expression anchoring operators:

ptfps -m destination_machines -users ^johndoe$,^janedoe$ -ppid 1

Note that on systems without regular expression support, strings must match exactly (case sensitive).

To view all processes that started within 24 hours, use

ptfps -m destination_machines -stime yesterday

To view all processes that are owned by "johndoe" and whose names begin with either a "q" or has parent pid 1, use:

ptfps -m destination_machines -users ^johndoe$ \( -names ^q -or -ppid 1 \)

Note that parentheses are necessary because the "AND" operator has higher precidence than the "OR" operator. There is an implicit "AND" operator between the term "-users ^johndoe$" and the expression "$ -names ^q -or -ppid 1 $". Also note that the parentheses are escaped because many shells require this to pass parentheses literally.

To send the HUP signal to all processes named "biff" owned by user johndoe, use

ptfps -m destination_machines -names ^biff$ -users ^johndoe$ -kill 1

Note that when using action terms, it is often very prudent to run ptfps with the same expression, but without the action. This will print the list of processes to which the action will be applied (provided no new processes that match the criteria are started between running ptfps without and with the action term). This will give a rough idea of what will happen when running ptfps with an action term.