.\" As its sole author, I explicitly place this file in the public domain.
.\" It may be used by anyone in any way for any purpose, though I would
.\" appreciate credit where it's due.
.\"		der Mouse, mouse@rodents.montreal.qc.ca, 1999-09-04
.Dd August 22, 2010
.Dt FINDPROC 1
.Os NetBSD 1.4T
.Sh NAME
.Nm findproc
.Nd process finder
.Sh SYNOPSIS
.Nm
.Op Fl k Ar sig
.Op Fl p
.Op Fl s
.Op Fl v
.Op Fl x
.Op Fl r
.Op Fl q
.Op Fl u
.Op Fl w
.Op Fl i Ar N
.Op Ar ps-arg
.Ar string
.Sh DESCRIPTION
.Nm
is a utility a la the common
.Ql ps\&\ \&|\&\ grep
idiom, designed for finding processes based on their command lines,
with numerous benefits as compared to actually piping
.Xr ps 1
output into
.Xr grep 1 .
In particular, it always filters out its own processes (both the
.Xr ps 1
process and
.Nm
itself), and it works to search for strings that produce false hits
with
.Xr grep 1
because they occur in places other than the command lines.  There are
also various flags to modify
.Nm findproc Ap s
behaviour in useful ways.
.Pp
By default,
.Nm
searches for
.Ar string
in the
.Sq COMMAND
field of
.Ql ps\&\ ax
output, printing the header line and the lines for any processes that
match the search string.  If
.Ar ps-arg
is given, it replaces the
.Ql ax
on the
.Xr ps 1
command line.  The flags modify this in various ways:
.Bl -tag -width indent
.It Fl k Ar sig
Does not print anything.  Instead, sends signal
.Ar sig
to every process found.
.Ar sig
can be a number or one of the short uppercase names such as
.Dv TERM
or
.Dv INT .
.It Fl p
Prints just the process IDs, without the rest of the lines.  Also
suppresses printing the
.Xr ps 1
header line.
.It Fl s
Suppresses output.  This disables printing error messages, the
.Xr ps 1
header, and the usual output for each matching process.  It is designed
for testing the exit status.
.Fl s
does not suppress
.Fl p
output, nor does it suppress complaints when
.Xr kill 2
fails for
.Fl k .
.It Fl v
Specifically enables printing the
.Xr ps 1
header and the
.Xr ps 1
output lines for matching processes.  This overrides options like
.Fl s
or
.Fl k
that normally suppress such output.
.It Fl x
Like
.Xr grep 1 Ap s
.Fl x
option, this changes the match criterion so that the whole command line
must match the search string, not just any substring of it.  This flag
is ignored if
.Fl r
is given (use
.Ql \&^
and
.Ql \&$
around the expression in that case).
.It Fl r
The search string is taken as a regular expression rather than a
literal string.
.It Fl q
Disables printing the
.Xr ps 1
header line, without affecting anything else.
.It Fl u
Suppresses normal output, like
.Fl s ,
but repeats the operation until it succeeds, that is, until it finds a
matching process.  When
.Nm
finally exits in this mode, it always does so successfully.
.It Fl w
Suppresses normal output, like
.Fl s ,
but repeats the operation while it succeeds, that is, while it finds a
matching process.  When
.Nm
finally exits in this mode, it always does so successfully.
.It Fl i Ar N
When
.Fl u
or
.Fl w
is used, this specifies the interval, in seconds, between checking for
matching processes; in the absence of
.Fl u
or
.Fl w ,
.Fl i Ap s
value does not affect anything.  The default is 60.
.El
.Pp
The exit code is normally 0 (success) if any processes were found; 1 if
none were; or 2 in case of
.Sq impossible
errors such as inability to parse the
.Xr ps 1
header, or for extra or insufficient args on the command line.  Some
options modify this; see above.
.Sh AUTHOR
der Mouse,
.Aq mouse@rodents.montreal.qc.ca .