Overview
pgrep looks through the running processes and prints the numbers (PIDs) of those that match a pattern. It saves the clumsy ps | grep and never lists itself. By default it matches the name of the program; with -f it matches the whole command line. Its exit status is 0 when it finds a match and 1 when it does not.
Background
Today the name covers pgrep from procps-ng, the pgrep that macOS ships and the pgrep applet in BusyBox. They agree on printing process numbers, on -f and on the exit statuses. pkill is the same search followed by a signal.
Examples
Find a background process by a word in its command line with -f; the number matches $!. The bounded wait lets it start, and the trap cleans it up on failure:
(
sleep 7$$ &
p=$!
trap 'kill "$p" 2>/dev/null || :' 0
n=0
until pgrep -f "sleep 7$$" >/dev/null; do
n=$((n + 1))
[ "$n" -lt 5 ] || exit 1
sleep 1
done
pgrep -f "sleep 7$$" | grep -c "^$p\$"
lookup_status=$?
kill "$p" 2>/dev/null || :
wait "$p" 2>/dev/null || :
trap - 0
exit "$lookup_status"
)
Use the exit status: 1 means that nothing matched, and nothing is printed:
pgrep -f "no-such-process-$$" || echo none
Count the matches by counting the lines of output:
(
sleep 7$$ &
p=$!
trap 'kill "$p" 2>/dev/null || :' 0
n=0
until pgrep -f "sleep 7$$" >/dev/null; do
n=$((n + 1))
[ "$n" -lt 5 ] || exit 1
sleep 1
done
pgrep -f "sleep 7$$" | grep -c .
lookup_status=$?
kill "$p" 2>/dev/null || :
wait "$p" 2>/dev/null || :
trap - 0
exit "$lookup_status"
)
Options
-f
Match the pattern against the full command line, not only the name.
-x
Match the name exactly, not as part of a longer name.
-l
Print the name next to each number.
Common mistakes
The pattern is a regular expression, so a name with a dot or a bracket matches more than you meant. Without -f, only the first part of a long command name is compared, so a long name may not match. pgrep -f name also matches the shell that you started it from if the name is in its own command line; the examples use a number that appears only in the process they start. Use -x to avoid matching sleep inside sleeping. Check the numbers before you pass them to kill.
Portability
Only -f and the exit status are in the Common examples. -l, -a and -c print different things on each system. The Common examples were executed on macOS system tools, procps-ng and BusyBox 1.37.0 (see the development guide for the exact check).
References
Original explanations, with upstream documentation for further reading. FreeBSD references are comparison material, not a claim of Apple version equivalence.