PFIND(1) proctools 0.4 PFIND(1) NAME pfind - find processes SYNOPSIS pfind [-V] [-S] [-d delim] [-f file | -M core] [-i] [-x] [expression] DESCRIPTION The pfind utility displays process IDs for those processes that match the given expression. The expression may be constructed from ``patterns'', ``primary expressions'' and ``operator expressions''. A pattern is any arbitrary text argument that is used to match the executable name or ar- guments of a process. A pattern on its own is equivalent to a -name ex- pression. Options, which must be specified before the expression, are: -d delim Use the specified delimiter to separate the process IDs instead of a newline. -f file Read process information from a platform-independent pfind `dump' file instead of the running kernel. Some actions will be unsup- ported. -i Use case-insensitive pattern matching. -M core Read process information from the given core instead of the run- ning kernel. Some actions will be unsupported. -S Print the search strategy and decision-making details to the standard error file descriptor. -V Prints the pfind version, then exits. -x Treat any pattern as a literal string for exact matching. Without this option, the default is to match as an extended regular ex- pression. For names, a full-length match will be sought. For ar- gument strings, the literal pattern may match any substring. The primary expressions for matching processes are: -any pattern Equivalent to ``( -name pattern -or -args pattern )''. -args pattern Match the pattern against the full command line of the process (equivalent to -full). Note: a process may have changed its com- mand line during execution. -ask Write a prompt to the standard error descriptor, then read a character from standard input. If the input is 'Y', 'y' or the user presses `enter', this expression acts as a ``match''. Other- wise, this expression acts as a ``non-match''. -euid euidlist Match only processes whose effective user ID is given (equivalent to -user). User IDs an be specified as usernames and as numeric user IDs. -gid gidlist Match only processes whose real group ID is listed (equivalent to -group). Group IDs can be specified as group names and numeric IDs. Non-existent numeric IDs do not cause errors. -name pattern The pattern is matched against the executable name of the pro- cess. See also the -x option. -pgrp pgrplist Match only processes that exist within the process groups speci- fied. -ppid ppidlist Match only processes whose parent process ID is specified (equiv- alent to -parent). -term termlist Match only processes whose controlling terminal is specified. Terminals can be specified as children of the /dev directory or, if starting with a leading slash (`/'), any currently mounted filename. Filenames specified must be character devices. -uid uidlist Match only processes whose real user ID is given. User IDs an be specified as usernames and as numeric user IDs. The primary expressions for taking action on matched processes are: -dump file Writes process information (about the process that is being con- sidered at the time the expression is evaluated) to the named file. The information can be read back with the -f option. Hope- fully, only pfind developers will ever need this expression. The file format is private to pfind and is probably not useful for anything else. -id Prints the process ID. This expression acts as a 'match' for all processes that matched any preceding expressions. This is also the default action for each process when -print, -ps or -result have not already been invoked. -kill signal Sends the specified signal to any processes that are already matched. If the signal was sent, this expression acts as a match. If an error occurred, this expression acts as a non-match and an error message is printed. The signal may be specified by its name, with or without the prepended `SIG', or as a number. Signals need not be preceded with a minus sign, but it is al- lowed. The -ps and -dump actions will not work fully if it oc- curs after the process has terminated. -print Prints the executable name of the process along with the process ID. This expression acts as a 'match'. -ps Prints the full argument string of the process along with the process ID. This expression acts as a 'match'. -result signal Sends the specified signal and waits for the process to termi- nate. The process ID and its exit code are printed. Specify signal 0 to wait for a process to terminate without actually sending a signal. The -result and -wait expressions should be considered `experimental'. If pfind itself terminates unexpected- ly (such as after SIGKILL), the monitored process might also be killed. It is also possible that pfind will interrupt the normal flow of signals from the monitored process to its parent. Stopped processes are treated as errors. For further details, see -kill. -timeout interval Waits up to interval seconds for the matched process to termi- nate, then the process ID and its exit code are printed. The ex- pression acts as a match in that case. If the interval elapses without the process terminating, this expression acts as a non- match and an error message is printed. The -timeout expression should be considered `experimental'. If pfind itself terminates unexpectedly (such as after SIGKILL), the monitored process might also be killed. It is also possible that pfind will interrupt the normal flow of signals from the monitored process to its parent. Stopped processes are treated as errors. -wait signal Sends the specified signal and waits for the process to termi- nate. Unlike -result, no output is produced when the process terminates. For further details, see -result. Some primary expressions have synonyms: -full pattern Equivalent to -args. -details Equivalent to -ps. -parent ppidlist Equivalent to -ppid. -group gidlist Equivalent to -gid. -s signal Equivalent to -kill. -then signal Equivalent to -kill. -user euidlist Equivalent to -euid. You may combine multiple primary expressions by forming operator expres- sions. The operator expressions are: ( expression ) Acts as a `match' if the parenthesised (nested) expression was a match, otherwise acts as a `non-match'. expression -and expression Acts as a match if the first expression was a match and the sec- ond expression was also a match. If the first expression was a non-match, the second expression is not evaluated, and overall this operator expression will act as a non-match. expression expression The same as ``expression -and expression''. expression -or expression Acts as a match if the first expression was a match or the first expression was a non-match and the second expression was a match. If the first expression was a match, the second expression is not evaluated, and overall this operator expression will act as a match. -not expression The expression will be evaluated normally but the result will be inverted. ! expression The same as ``-not expression''. -if Allows expressions to be evaluated on both success and failure of a previous expression. (The -and and -or expressions only allow further expression upon either success or failure, respectively.) The full syntax is ``-if expression -do expression -else expression -endif''. Overall, an -if expression evaluates as a `match' regardless of its inner expressions. Note that all expressions (primary expressions and operator expressions) are evaluated left-to-right and there is no other operator precedence. (The only exceptions are the -not and -if types of operator expressions.) EXAMPLES pfind . Prints the process IDs of all processes. pfind -d , Prints the process IDs of all processes, separated by commas. pfind -d Prints the process IDs of all processes whose names match ``-d'', believe it or not! pfind sendmail pfind -name sendmail pfind -args sendmail pfind -any sendmail Print the process IDs of all sendmail processes. pfind -not -gid daemon Prints the process IDs of all processes whose group ID is not daemon. pfind -d , -uid root sh Prints the process IDs of all shells whose effective user ID is root, separated by commas. pfind -d, -uid root sh Prints the process IDs of root-owned processes whose names match both `sh' and `-d,'. pfind '(' -uid root -or sh ')' -print pfind -if -uid root -or sh -do -print Match process that are either owned by root or match ``sh'' in their names, and print the IDs and names for all such processes. Print nothing for non-matched processes. pfind -uid root -or sh -print pfind -uid root -or '(' sh -print ')' Print the process IDs of all root's processes, and both the IDs and names for processes with names matching ``sh''. pfind -user root -any perl -details -ask -then QUIT Matches 'perl' against the names and command lines of root's processes. For each process, prints the command line then asks you whether to send SIGQUIT. pfind -i -f filename sh Prints the IDs of all processes described in the file `filename' whose names match `sh', `Sh', `sH', or `SH'. pfind -if filename sh Prints the IDs of all processes whose names match both the literal string `filename' and the literal string `sh'. This is because `-if' is inter- preted as the start of an -if expression. RETURN VALUES The pfind utility exits with one of the following values: 0 (EX_OK) One or more processes were matched. 1 No processes were matched. 64 (EX_USAGE) Invalid command-line options were specified. 69 (EX_UNAVAILABLE) An unexpected error occurred. 70 (EX_SOFTWARE) A feature was not supported in the current environment. 71 (EX_OSERR) A transient error occurred. CAVEATS pfind evaluates expressions left-to-right without the operator precedence that users might intuitively expect. This saves pfind from having to re- order expressions or enforce a strict grammar. So, be warned that -and and -or do not take precedence over other operataor expressions. Use brackets, -if expressions and the -S option whenever necessary. The expression is evaluated for each process sequentially. That is, pro- cesses are examined ``one after the other'' from a list that is generated at the start of each pfind invocation. It is tempting to construct pfind expressions that will match many pro- cesses and performs many actions. However, pfind suffers from the same flaw as any process examination tool: by the time the the PID information is collected, it is out-of-date. Therefore, one long-running expression may cause subsequent expressions to match new processes that have the same PIDs as old processes. The current pfind process will not consider itself to be a potential match. However, it is possible for a user to construct a shell pipeline that contains processes that will be matched by the expression. Some users might not anticipate this. The output of this tool should never be treated as accurate programmatic input (process names and arguments will have been escaped for safe print- ing on the terminal). Unlike other proctools tools, pfind does not use `getopt' argument pars- ing. This means that you may not combine separate options into a single argument, and arguments for the -d and -f options must follow as separate arguments. pfind does not include a grammar checker. Therefore, it is highly likely that it will not produce any warnings about erroneous expressions. As a consequence, you can put an incomplete -not expression at the end of a nested expression to invert it entirely. For example: pfind -if -user root -or -user daemon -not -do -id -else -kill 9 -endif The above command line prints the IDs of all root or daemon processes and kills all others. pfind -if -not '(' -user root -or -user daemon ')' -do -id -else -kill 9 -endif The above command line is a proper, but longer, equivalent to the previ- ous command line. BUGS Output of the -ps action may vary between operating systems. For the sysctl mode of operation (e.g. Darwin) the -ps option will list process belonging to other users but will be unable to display details of their arguments. A question mark and executable name (but not the argu- ment string) will be displayed. (The Darwin ps can only show arguments because it is setuid root.) Session ID is not a supported criterion. pfind does not offer features that require the comparison of information among multiple processes. For example, pfind has no equivalent for the pgrep -n option. SEE ALSO pgrep(1), regex(3) HISTORY The pfind command was added in proctools version 0.4. AUTHORS Feedback may be sent to <j-devenish/users.sourceforge.net>. pfind is based on proctools by <wfaulk/users.sourceforge.net>. The project home- page is at <http://proctools.sourceforge.net>. 06 December 2003 6