Add -c/--command regex filter for cmdline matching

Author: AndPuQing

CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- New `-c/--command <regex>` option to filter processes by a regex against the command line (repeatable; works in batch and interactive modes)
+
 ## [0.2.5] - 2026-08-08
 
 ### Changed

Cargo.lock

@@ -46,6 +46,7 @@ futures = { version = "0.3", default-features = false }
 chrono = { version = "0.4", default-features = false, features = ["clock"] }
 serde = { version = "1", default-features = false, features = ["derive"] }
 serde_json = "1"
+regex = "1"
 linux-taskstats = { path = "patches/linux-taskstats", default-features = false, version = "0.7" }
 
 [profile.release]

Cargo.toml

@@ -110,6 +110,12 @@ Monitor user's processes:
 sudo iotop -u www-data
 ```
 
+Filter by command-line regex:
+```bash
+sudo iotop -c bash
+sudo iotop -c '^sshd' -c 'nginx.*worker'
+```
+
 Batch mode with timestamps:
 ```bash
 sudo iotop -t -b -n 10 > iotop.log
@@ -140,6 +146,7 @@ sudo iotop -b --csv -t -q -n 5
 | `-b` | `--batch` | Batch mode (non-interactive) |
 | `-p` | `--pid` | Monitor specific processes/threads (can be repeated) |
 | `-u` | `--user` | Monitor processes by username or UID (can be repeated) |
+| `-c` | `--command` | Only show processes whose command line matches the regex (can be repeated) |
 | `-t` | `--time` | Add timestamp on each line (implies `--batch`) |
 | `-q` | `--quiet` | Suppress column names and headers (implies `--batch`) |
 | `-k` | `--kilobytes` | Use kilobytes instead of human-friendly units |

README.md

@@ -5,7 +5,7 @@ _iotop() {
     COMPREPLY=()
     cur="${COMP_WORDS[COMP_CWORD]}"
     prev="${COMP_WORDS[COMP_CWORD-1]}"
-    opts="-o --only -P --processes -a --accumulated -d --delay -n --iter -b --batch -p --pid -u --user -t --time -q --quiet -k --kilobytes --json --csv -h --help"
+    opts="-o --only -P --processes -a --accumulated -d --delay -n --iter -b --batch -p --pid -u --user -c --command -t --time -q --quiet -k --kilobytes --json --csv -h --help"
 
     case "${prev}" in
         -d|--delay)
@@ -28,6 +28,11 @@ _iotop() {
             COMPREPLY=( $(compgen -u -- ${cur}) )
             return 0
             ;;
+        -c|--command)
+            # Complete with running command names
+            COMPREPLY=( $(compgen -W "$(ps -e -o comm= | sort -u | tr '\n' ' ')" -- ${cur}) )
+            return 0
+            ;;
         *)
             ;;
     esac

completions/iotop.bash

@@ -9,6 +9,7 @@ complete -c iotop -s n -l iter -d 'Number of iterations before ending' -x -a '5
 complete -c iotop -s b -l batch -d 'Batch mode (non-interactive)'
 complete -c iotop -s p -l pid -d 'Processes/threads to monitor' -x -a '(__fish_complete_pids)'
 complete -c iotop -s u -l user -d 'Users to monitor' -x -a '(__fish_complete_users)'
+complete -c iotop -s c -l command -d 'Only show processes whose command line matches the regex' -x
 complete -c iotop -s t -l time -d 'Add timestamp on each line (implies --batch)'
 complete -c iotop -s q -l quiet -d 'Suppress column names and headers (implies --batch)'
 complete -c iotop -s k -l kilobytes -d 'Use kilobytes instead of human-friendly units'

completions/iotop.fish

@@ -12,6 +12,7 @@ _iotop() {
         '(-b --batch)'{-b,--batch}'[batch mode (non-interactive)]'
         '*'{-p,--pid}'[processes/threads to monitor]:pid:_pids'
         '*'{-u,--user}'[users to monitor]:user:_users'
+        '*'{-c,--command}'[only show processes whose command line matches the regex]:regex:_command_names -e'
         '(-t --time)'{-t,--time}'[add timestamp on each line (implies --batch)]'
         '(-q --quiet)'{-q,--quiet}'[suppress column names and headers (implies --batch)]'
         '(-k --kilobytes)'{-k,--kilobytes}'[use kilobytes instead of human-friendly units]'

completions/iotop.zsh

@@ -59,6 +59,11 @@ Threads of the specified process are also monitored.
 Monitor only processes belonging to the specified user(s). The argument can be either a username
 or a numeric UID. This option can be repeated to monitor multiple users.
 .TP
+.BR \-c ", " \-\-command " \fIREGEX\fR"
+Only show processes whose command line matches the given regular expression. This option can be
+repeated to combine several patterns (a process is shown if it matches any of them). Works in both
+batch and interactive modes. Invalid patterns are rejected at startup.
+.TP
 .BR \-t ", " \-\-time
 Add a timestamp on each line in batch mode (implies \fB\-\-batch\fR). The timestamp format is HH:MM:SS.
 .TP
@@ -183,6 +188,11 @@ Monitor specific process and show only processes (not threads):
 Monitor all processes of a specific user:
 .B sudo iotop \-u www-data
 .TP
+Filter by command-line regex:
+.B sudo iotop \-c bash
+.TP
+.B sudo iotop \-c '^sshd' \-c 'nginx.*worker'
+.TP
 Batch mode with timestamps and quiet output:
 .B sudo iotop \-tq \-n 10 > iotop.log
 .TP

doc/iotop.8

@@ -9,7 +9,8 @@ use argh::FromArgs;
 use crossterm::event::MouseEventKind;
 use crossterm::event::{KeyCode, KeyModifiers};
 use nix::unistd::User;
-use process::{ProcessList, ProcessSnapshot};
+use process::{ProcessInfo, ProcessList, ProcessSnapshot};
+use regex::Regex;
 use taskstats::{TaskStats, TaskStatsConnection};
 use tokio_util::sync::CancellationToken;
 use ui::{Event, SortColumn, Tui, UIState};
@@ -54,6 +55,10 @@ struct Args {
     #[argh(option, short = 'u')]
     user: Vec<String>,
 
+    /// regex to match against the command line (can be repeated)
+    #[argh(option, short = 'c')]
+    command: Vec<String>,
+
     /// add timestamp on each line (implies --batch)
     #[argh(switch, short = 't')]
     time: bool,
@@ -85,6 +90,9 @@ async fn main() -> Result<()> {
     // Resolve usernames to UIDs
     let uids = resolve_users(&args.user)?;
 
+    // Compile command-line regex filters (invalid patterns abort early)
+    let command_regexes = compile_command_regexes(&args.command)?;
+
     // Connect to taskstats
     let taskstats_conn = TaskStatsConnection::new()?;
     warn_if_taskstats_unreadable(&taskstats_conn);
@@ -93,9 +101,9 @@ async fn main() -> Result<()> {
         .with_uids(uids.clone());
 
     if args.batch || args.time || args.quiet || args.json || args.csv {
-        run_batch_mode(&mut process_list, &args)?;
+        run_batch_mode(&mut process_list, &args, &command_regexes)?;
     } else {
-        run_interactive_mode(&mut process_list, &args).await?;
+        run_interactive_mode(&mut process_list, &args, &command_regexes).await?;
     }
 
     Ok(())
@@ -167,7 +175,32 @@ fn resolve_users(users: &[String]) -> Result<Vec<u32>> {
     Ok(uids)
 }
 
-async fn run_interactive_mode(process_list: &mut ProcessList, args: &Args) -> Result<()> {
+/// Compile the `-c/--command` regex filters. Returns an error describing the
+/// offending pattern so invalid regexes fail fast at startup.
+fn compile_command_regexes(patterns: &[String]) -> Result<Vec<Regex>> {
+    patterns
+        .iter()
+        .map(|p| {
+            Regex::new(p).map_err(|e| anyhow::anyhow!("invalid command regex {:?}: {}", p, e))
+        })
+        .collect()
+}
+
+/// Filter a process list in place so only processes whose command line matches
+/// at least one of the given regexes remain. When `regexes` is empty no
+/// filtering is applied. Used by batch and interactive modes alike.
+fn filter_by_command(processes: &mut Vec<&ProcessInfo>, regexes: &[Regex]) {
+    if regexes.is_empty() {
+        return;
+    }
+    processes.retain(|p| regexes.iter().any(|re| re.is_match(p.get_cmdline())));
+}
+
+async fn run_interactive_mode(
+    process_list: &mut ProcessList,
+    args: &Args,
+    command_regexes: &[Regex],
+) -> Result<()> {
     let mut tui = Tui::new()?;
     tui.enter()?;
 
@@ -212,7 +245,13 @@ async fn run_interactive_mode(process_list: &mut ProcessList, args: &Args) -> Re
 
                     }
                     Event::DataUpdate(snapshot) => {
-                        render_snapshot(&mut tui, &snapshot, &mut state, has_delay_acct)?;
+                        render_snapshot(
+                            &mut tui,
+                            &snapshot,
+                            &mut state,
+                            has_delay_acct,
+                            command_regexes,
+                        )?;
 
                         // Check iteration limit
                         if let Some(max_iter) = args.iterations {
@@ -224,7 +263,13 @@ async fn run_interactive_mode(process_list: &mut ProcessList, args: &Args) -> Re
                     }
                     Event::Render => {
                         if let Some(ref snapshot) = current_snapshot {
-                            render_snapshot(&mut tui, snapshot, &mut state, has_delay_acct)?;
+                            render_snapshot(
+                                &mut tui,
+                                snapshot,
+                                &mut state,
+                                has_delay_acct,
+                                command_regexes,
+                            )?;
                         }
                     }
                     Event::Key(key) => match key.code {
@@ -418,12 +463,14 @@ fn render_snapshot(
     snapshot: &ProcessSnapshot,
     state: &mut UIState,
     has_delay_acct: bool,
+    command_regexes: &[Regex],
 ) -> Result<()> {
     let mut processes: Vec<&process::ProcessInfo> = snapshot.processes.values().collect();
 
     if state.only_active {
         processes.retain(|p| p.did_some_io(state.accumulated));
     }
+    filter_by_command(&mut processes, command_regexes);
 
     sort_processes(&mut processes, state);
 
@@ -515,14 +562,18 @@ fn sort_processes(processes: &mut Vec<&process::ProcessInfo>, state: &UIState) {
 /// Batch mode outputs process I/O statistics to stdout in a parseable format.
 /// This function gracefully handles broken pipe errors (e.g., when output is
 /// piped to `head` or similar utilities) by returning Ok(()) when write errors occur.
-fn run_batch_mode(process_list: &mut ProcessList, args: &Args) -> Result<()> {
+fn run_batch_mode(
+    process_list: &mut ProcessList,
+    args: &Args,
+    command_regexes: &[Regex],
+) -> Result<()> {
     // Machine-readable output modes take precedence over the plain-text batch
     // output. They share the same refresh loop and iteration/delay semantics.
     if args.json {
-        return run_json_mode(process_list, args);
+        return run_json_mode(process_list, args, command_regexes);
     }
     if args.csv {
-        return run_csv_mode(process_list, args);
+        return run_csv_mode(process_list, args, command_regexes);
     }
 
     use std::io::{self, Write};
@@ -607,6 +658,7 @@ fn run_batch_mode(process_list: &mut ProcessList, args: &Args) -> Result<()> {
         if args.only {
             processes.retain(|p| p.did_some_io(args.accumulated));
         }
+        filter_by_command(&mut processes, command_regexes);
 
         processes.sort_by(|a, b| {
             let stats_a = if args.accumulated {
@@ -786,7 +838,11 @@ fn collect_row(process: &process::ProcessInfo, accumulated: bool, duration: f64)
 
 /// Batch mode with `--json`: emit one JSON object per iteration, containing the
 /// iteration timestamp, total/actual disk I/O, and the process list.
-fn run_json_mode(process_list: &mut ProcessList, args: &Args) -> Result<()> {
+fn run_json_mode(
+    process_list: &mut ProcessList,
+    args: &Args,
+    command_regexes: &[Regex],
+) -> Result<()> {
     use std::io::{self, Write};
     use std::thread;
     use std::time::Duration;
@@ -806,6 +862,7 @@ fn run_json_mode(process_list: &mut ProcessList, args: &Args) -> Result<()> {
         if args.only {
             processes.retain(|p| p.did_some_io(args.accumulated));
         }
+        filter_by_command(&mut processes, command_regexes);
         sort_processes_by_io(&mut processes, args);
 
         let rows: Vec<serde_json::Value> = processes
@@ -864,7 +921,11 @@ fn csv_field(value: &str) -> String {
 /// Batch mode with `--csv`: emit one CSV row per process per iteration. A header
 /// row is printed before the first iteration (unless `--quiet`). With `--time` a
 /// leading time column is added. Compatible with `-t`/`-q`.
-fn run_csv_mode(process_list: &mut ProcessList, args: &Args) -> Result<()> {
+fn run_csv_mode(
+    process_list: &mut ProcessList,
+    args: &Args,
+    command_regexes: &[Regex],
+) -> Result<()> {
     use std::io::{self, Write};
     use std::thread;
     use std::time::Duration;
@@ -887,6 +948,7 @@ fn run_csv_mode(process_list: &mut ProcessList, args: &Args) -> Result<()> {
         if args.only {
             processes.retain(|p| p.did_some_io(args.accumulated));
         }
+        filter_by_command(&mut processes, command_regexes);
         sort_processes_by_io(&mut processes, args);
 
         if !args.quiet && !header_printed {
@@ -952,3 +1014,82 @@ fn run_csv_mode(process_list: &mut ProcessList, args: &Args) -> Result<()> {
     }
     Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn process_with_cmdline(pid: i32, cmdline: &str) -> ProcessInfo {
+        let mut p = ProcessInfo::new(pid);
+        p.cmdline = Some(cmdline.to_string());
+        p
+    }
+
+    fn refs(owned: &mut [ProcessInfo]) -> Vec<&ProcessInfo> {
+        owned.iter().collect()
+    }
+
+    #[test]
+    fn test_compile_command_regexes_valid() {
+        let regexes = compile_command_regexes(&["bash".to_string(), "ssh.*".to_string()]).unwrap();
+        assert_eq!(regexes.len(), 2);
+    }
+
+    #[test]
+    fn test_compile_command_regexes_invalid() {
+        assert!(compile_command_regexes(&["[".to_string()]).is_err());
+    }
+
+    #[test]
+    fn test_filter_by_command_empty_noop() {
+        let mut owned = vec![
+            process_with_cmdline(1, "bash"),
+            process_with_cmdline(2, "sshd -D"),
+        ];
+        let mut processes = refs(&mut owned);
+        filter_by_command(&mut processes, &[]);
+        assert_eq!(processes.len(), 2);
+    }
+
+    #[test]
+    fn test_filter_by_command_matches_substring() {
+        let mut owned = vec![
+            process_with_cmdline(1, "/usr/bin/bash --login"),
+            process_with_cmdline(2, "sshd: root@pts/0"),
+            process_with_cmdline(3, "nginx: worker"),
+        ];
+        let regexes = compile_command_regexes(&["bash".to_string()]).unwrap();
+        let mut processes = refs(&mut owned);
+        filter_by_command(&mut processes, &regexes);
+        assert_eq!(processes.len(), 1);
+        assert_eq!(processes[0].pid, 1);
+    }
+
+    #[test]
+    fn test_filter_by_command_multiple_regexes_any() {
+        let mut owned = vec![
+            process_with_cmdline(1, "bash"),
+            process_with_cmdline(2, "nginx"),
+            process_with_cmdline(3, "sleep 10"),
+        ];
+        let regexes =
+            compile_command_regexes(&["bash".to_string(), "nginx".to_string()]).unwrap();
+        let mut processes = refs(&mut owned);
+        filter_by_command(&mut processes, &regexes);
+        let remaining: Vec<i32> = processes.iter().map(|p| p.pid).collect();
+        assert_eq!(remaining, vec![1, 2]);
+    }
+
+    #[test]
+    fn test_filter_by_command_regex_anchoring() {
+        let mut owned = vec![
+            process_with_cmdline(1, "bash"),
+            process_with_cmdline(2, "notbash"),
+        ];
+        let regexes = compile_command_regexes(&["^bash$".to_string()]).unwrap();
+        let mut processes = refs(&mut owned);
+        filter_by_command(&mut processes, &regexes);
+        assert_eq!(processes.len(), 1);
+        assert_eq!(processes[0].pid, 1);
+    }
+}