// LSOFRS — LIST SYSTEM OPEN FILES IN RUST

Quickstart

Install from crates.io or source. The same binary is published twice — lsofrs (long) and lsf (short, quicker to type):

# install
cargo install lsofrs

# from source
git clone https://github.com/MenkeTechnologies/lsofrs
cd lsofrs && cargo build --release
sudo cp target/release/lsf /usr/local/sbin/

# everyday queries
lsf                           # list all open files
lsf -p 1234                   # files for PID 1234
lsf -c Chrome                 # files for Chrome processes
lsf -u root                   # files for root user
lsf -i                        # network connections only
lsf -i :8080                  # who's listening on port 8080
lsf /path/to/file             # who has this file open
lsf -t -c nginx               # just PIDs (for scripting)

# pipelines
lsf --json | jq '.[] | select(.fd == "cwd")'
lsf --csv  > snapshot.csv
lsf -F pcfn                   # field output (p=pid, c=cmd, f=fd, n=name)

Full install + usage live in the README. Man page: man lsofrs (310-line roff under lsofrs.1). Zsh completion ships under completions/_lsofrs.

Why lsofrs — Wall-Clock Comparison

Benchmarked on macOS with hyperfine (10 runs, 3 warmup, ~470 processes / ~5000 open files). Numbers are reproducible from README §PERFORMANCE.

Feature parity vs incumbents

Overview

• CLI front-end — clap derive parser in src/cli.rs (1,341 lines, 38 #[arg(...)] attributes). main.rs dispatches to the active mode based on which flag is set.
• Platform gather — src/darwin.rs (1,253 lines, libproc FFI), src/linux.rs (820 lines, /proc reader), src/freebsd.rs (835 lines, sysctl + procfs). All three return the same Vec<Process> from types.rs; each per-PID FD scan is parallelized with rayon's work-stealing pool.
• Selection — src/filter.rs (2,812 lines) implements OR-mode (default) and AND-mode (-a) filter composition over PID / PGID / user / command / FD / network-spec / path. Supports comma-lists, ranges (0-10), exclusion (^root), and regex (/nginx|apache/).
• Output — src/output.rs (columnar + field), src/json.rs (serde), src/csv_out.rs (RFC 4180). TTY detection auto-switches between cyberpunk headers (H4XOR / CL4SS / T4RGET) and plain headers for pipelines.
• Live modes — --tui (7-tab dashboard, 5,312 lines), --top (1,008 lines), --summary -r (904 lines), --monitor (288 lines), --watch FILE, --follow PID, --leak-detect. All share src/tui_app.rs's TuiMode trait for common keybindings, alternate-screen entry/exit, and atomic frame rendering.
• Themes — src/theme.rs (1,005 lines) defines 31 named palettes via the ThemeName enum. Custom 6-color themes persist to ~/.lsofrs.conf through src/config.rs (TOML).

Modes — one card per entry point

Selection grammar

Every selector is independent and composable. By default selectors OR together; -a switches the entire predicate to AND mode. Negation via ^, ranges via N-M, regex via /…/.

lsf -p 1234,5678               # PIDs 1234 OR 5678
lsf -u root,wizard             # users root OR wizard
lsf -p ^1234                   # everything except PID 1234
lsf -u ^root                   # everything except root
lsf -d 0-10                    # FDs 0 through 10
lsf -c '/nginx|apache/'        # command name matches regex

lsf -a -p 1234 -i              # AND: PID 1234 AND has network FD
lsf -a -u nginx -i TCP:443     # AND: nginx user AND TCP/443

lsf -i                         # any network FD
lsf -i 4                       # IPv4 only
lsf -i 6                       # IPv6 only
lsf -i TCP                     # TCP only
lsf -i :443                    # any protocol on port 443
lsf -i TCP:443                 # TCP on port 443

Cyberpunk theming

When stdout is a TTY, column headers swap from utilitarian (COMMAND / PID / USER) to cyberpunk (PROCESS / PRC / H4XOR) and ANSI coloring activates. Piped output is always plain — safe for scripts. 31 named palettes ship in src/theme.rs:

Inside any TUI mode press c for the theme chooser (live preview), C for the 6-color editor. Selections persist to ~/.lsofrs.conf via src/config.rs.

Interactive controls (shared across TUI modes)

--tui adds tab navigation (Tab / BackTab / 1–7 / click). --top adds s sort, r reverse, +/- grow/shrink, b bar toggle, d delta toggle.

Architecture in one screen

src/
├── main.rs        # 282  CLI entry, mode dispatch, repeat/leak loops
├── cli.rs         # 1,341 clap derive args (38 #[arg], 20 short flags)
├── types.rs       # 867  Process, OpenFile, SocketInfo, NetSpec, …
├── darwin.rs      # 1,253 macOS libproc FFI (zero-copy repr(C))
├── linux.rs       # 820  /proc reader (parallel per-PID via rayon)
├── freebsd.rs     # 835  sysctl + procfs reader
├── filter.rs      # 2,812 selection & filter composition (AND/OR, regex)
├── strutil.rs     # 76   safe UTF-8 truncation for fixed-width display
├── output.rs      # 772  columnar & field formatting, ANSI theming
├── json.rs        # serde JSON
├── csv_out.rs     # RFC 4180 CSV
├── monitor.rs     # 288  classic full-screen alternate-buffer monitor
├── follow.rs      # 369  single-PID FD tracker (status transitions)
├── leak.rs        # 339  circular-buffer FD-count leak detector
├── delta.rs       # iteration-diff engine for change highlighting
├── summary.rs     # 904  aggregate stats + bars (+ live TUI mode)
├── tree.rs        # 556  process tree w/ FD inheritance
├── tui_app.rs     # 564  shared TuiMode trait (ratatui)
├── tui_tabs.rs    # 5,312 unified 7-tab TUI (mouse, tooltips)
├── theme.rs       # 1,005 31 themes + custom palette support
├── config.rs      # TOML config persistence (~/.lsofrs.conf)
├── top.rs         # 1,008 live top-N FD dashboard
├── watch.rs       # 369  file-open/close watch
├── stale.rs       # 313  deleted-file FD finder
├── ports.rs       # 450  listening-ports summary
├── pipe_chain.rs  # 358  pipe / unix-socket IPC topology
└── net_map.rs     # 608  connections grouped by remote host
lsofrs.1           # 310-line roff man page
completions/_lsofrs # 101-line zsh completion (#compdef lsofrs)

Platform support matrix

Each platform module is gated by #[cfg(target_os = "…")] in src/lib.rs. The shared Process / OpenFile / SocketInfo shapes live in src/types.rs (867 lines, 11 public structs / enums) — every gather backend returns the same data, so the entire stack above filter.rs is platform-agnostic.

Why it's fast

• Zero-copy FFI. Darwin gather uses raw #[repr(C)] structs sized to kernel headers — no intermediate parse step, no allocator pressure per-FD.
• Rayon work-stealing per-PID. Each PID's FD scan runs on its own worker; CPU count = parallel degree.
• Username caching. v4.8.0 added a OnceCell-backed getpwuid cache — previously the hot loop called the syscall once per record.
• Precomputed filter paths. The filter predicate canonicalizes its lookups once before the gather pass, not per-FD.
• Streaming output. No intermediate Vec<Record> for the common path — gather → filter → format → write goes through the same iterator chain.
• serde + clap derive. No hand-rolled JSON escaping, no hand-rolled getopt loop.

Net result: 14.2 ms wall-clock for the default lsf invocation vs 169.8 ms for lsof 4.91 on the same machine (hyperfine, ~470 procs, ~5000 FDs).

JSON shape

--json emits an array of records. Each record is the public OpenFile serialization from src/types.rs:

[
  {
    "pid": 1234,
    "ppid": 1,
    "pgid": 1234,
    "uid": 0,
    "user": "root",
    "command": "nginx",
    "fd": "10u",
    "type": "IPv4",
    "device": "0x0",
    "size_off": null,
    "node": "TCP",
    "name": "*:8080 (LISTEN)",
    "socket": {
      "protocol": "TCP",
      "local_addr": "0.0.0.0",
      "local_port": 8080,
      "remote_addr": null,
      "remote_port": null,
      "state": "LISTEN"
    }
  }
]

Hard-coded JSON contract tests live in tests/json_shape.rs, tests/json_wrappers.rs, and tests/json_and_csv_contracts.rs (233 #[test] functions in the latter alone) — refactors can't silently break downstream consumers.

Where to go next

• Engineering report — per-subsystem LOC, top-20 files, dependency table, test surface.
• README — full install, every flag, full benchmark table.
• docs.rs/lsofrs — rustdoc for the library crate (pub mod cli; pub mod types; pub mod filter; …).
• lsofrs.1 — 310-line roff man page (also man lsofrs after install).