procutils-pkill 0.2.0

Signal processes based on name and other attributes
Documentation

pkill

Signal processes based on name and other attributes.

Description

Looks up processes based on name and other attributes, then sends a signal to each matching process. Uses the same matching logic as pgrep. By default, sends SIGTERM.

Inputs

  • /proc/[pid]/stat -- process status (PID, comm, state, PPID, pgrp, session, tty, starttime)
  • /proc/[pid]/status -- effective and real UID/GID
  • /proc/[pid]/cmdline -- full command line (for -f matching)
  • /proc/uptime -- system uptime (for --older calculations)
  • kill() syscall via rustix -- sends signals to matched processes

Arguments

Pattern

Argument Description
pattern (positional, optional) Extended regex to match against process names

Signal selection

Flag Description
--signal SIGNAL Signal to send, by name or number (default: TERM)

Output options

Flag Description
-c, --count Print count of matched processes instead of signaling
-e, --echo Display name and PID of each signaled process

Matching options

Flag Description
-f, --full Match pattern against full command line, not just process name
-i, --ignore-case Case-insensitive pattern matching
-x, --exact Require exact match of the process name (not a substring)

Selection filters

Flag Description
-n, --newest Select only the most recently started matching process
-o, --oldest Select only the earliest started matching process
-O, --older SECS Select processes older than SECS seconds
-P, --parent PPID,... Match only processes whose parent PID is listed
-g, --pgroup PGRP,... Match only processes in the listed process groups
-G, --group GID,... Match only processes with the listed real group IDs
-s, --session SID,... Match only processes in the listed sessions
-t, --terminal TERM,... Match only processes on the listed controlling terminals
-u, --euid UID,... Match only processes with the listed effective user IDs or names
-U, --uid UID,... Match only processes with the listed real user IDs or names
-r, --runstates STATE,... Match only processes in the listed run states (R, S, D, Z, T, etc.)

Note: -v (inverse matching) is intentionally not supported in pkill, matching procps-ng behavior.

Behavior

pkill iterates over all processes in /proc, applies the same filtering and pattern matching logic as pgrep, then sends a signal to each matched process.

Signal parsing

The --signal value is resolved in the following order:

  1. Named signal without prefix: TERM, HUP, KILL, etc.
  2. Named signal with SIG prefix: SIGTERM, SIGHUP, SIGKILL, etc.
  3. Numeric signal: 15, 1, 9, etc.

Supported signal names: HUP, INT, QUIT, ILL, TRAP, ABRT (IOT), BUS, FPE, KILL, USR1, SEGV, USR2, PIPE, ALRM, TERM, STKFLT, CHLD (CLD), CONT, STOP, TSTP, TTIN, TTOU, URG, XCPU, XFSZ, VTALRM, PROF, WINCH, IO (POLL), PWR, SYS.

Process matching

The matching algorithm is shared with pgrep:

  • The invoking process (pkill itself) is always excluded from matches.
  • Without -f, the pattern is matched against the process comm name.
  • With -f, the pattern is matched against the full command line.
  • With -x, the pattern must match the entire name (anchored match).
  • Selection filters (parent, group, terminal, etc.) are combined with AND logic.
  • -n and -o are applied after all other filtering.

Echo mode (-e)

When --echo is specified, pkill prints a line for each successfully signaled process:

name killed (pid N)

Count mode (-c)

When --count is specified, pkill prints the number of matching processes instead of sending signals.

Exit codes

Code Meaning
0 At least one process was matched and successfully signaled
1 No processes matched, or signaling failed for all matches
2 Syntax error in command line arguments
3 Fatal error

Divergences from procps-ng

pkill shares its matching engine with pgrep.

Error messages for invalid arguments use different wording.