// 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 man/man1/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,343 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,308 lines), --top (1,009 lines), --summary -r (1,026 lines), --monitor (398 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

Full flag reference

Every flag below is a real #[arg(…)] in src/cli.rs (38 attributes total). Short flags follow the original lsof letters; long flags name the lsofrs-specific modes. +/- toggles (+r/-r, +w/-w, +d/+D) mirror lsof's prefix grammar.

Selection

Network

Display & output

Modes & live system

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.

Configuration

Settings persist to ~/.lsofrs.conf, a TOML file read and written by src/config.rs (Prefs struct). The TUI auto-saves every change made via keybinds; you can also edit the file by hand. A documented template ships as lsofrs.default.conf — copy it to ~/.lsofrs.conf or let lsofrs create one on first run.

# ~/.lsofrs.conf
theme = "NeonSprawl"      # one of the 31 named palettes
refresh_rate = 1          # seconds between refreshes in live modes
hover_tooltips = true     # auto-tooltips after 1s hover (T toggles; right-click always works)

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        # 283  CLI entry, mode dispatch, repeat/leak loops
├── cli.rs         # 1,343 clap derive args (38 #[arg], 20 short flags)
├── types.rs       # 972  Process, OpenFile, SocketInfo, NetworkFilter, FileType, …
├── 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      # 793  columnar & field formatting, ANSI theming
├── json.rs        # serde JSON
├── csv_out.rs     # RFC 4180 CSV
├── monitor.rs     # 398  classic full-screen alternate-buffer monitor
├── follow.rs      # 192  single-PID FD tracker (status transitions)
├── leak.rs        # 340  circular-buffer FD-count leak detector
├── delta.rs       # iteration-diff engine for change highlighting
├── summary.rs     # 1,026 aggregate stats + bars (+ live TUI mode)
├── tree.rs        # 556  process tree w/ FD inheritance
├── tui_app.rs     # 572  shared TuiMode trait (ratatui)
├── tui_tabs.rs    # 5,308 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,009 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
man/man1/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 (972 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 / -J emits an array of process records; each process carries a nested files array. The shape is produced by JsonProcess / JsonFile in src/json.rs (verbatim sample from lsf -i TCP --json). Optional fields are omitted when empty (#[serde(skip_serializing_if = "Option::is_none")]):

[
  {
    "command": "rapportd",
    "pid": 667,
    "uid": 501,
    "pgid": 667,
    "ppid": 1,
    "files": [
      {
        "fd": "10u",
        "type": "IPv4",
        "size_off": 0,
        "access": "u",
        "name": "*:60865 (LISTEN)",
        "protocol": "TCP",
        "tcp_state": "LISTEN"
      }
    ]
  }
]

Per-file keys: fd, type (from the FileType enum), device ("maj,min"), size_off, node (inode), access (r/w/u), lock, name, and — for sockets — protocol + tcp_state. 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; …).
• man/man1/lsofrs.1 — 310-line roff man page (also man lsofrs after install).