██▓ ██████ ▒█████ █████▒██████ ██████
▓██▒ ▒██ ▒ ▒██▒ ██▒▓██ ▒██ ▒ ▒██ ▒
▒██░ ░ ▓██▄ ▒██░ ██▒▒████ ░▓██▄ ░ ▓██▄
▒██░ ▒ ██▒▒██ ██░░▓█▒ ░▒ ██▒ ▒ ██▒
░██████▒▒██████▒▒░ ████▓▒░░▒█░ ▒██████▒▒██████▒▒
░ ▒░▓ ░▒ ▒▓▒ ▒ ░░ ▒░▒░▒░ ▒ ░ ▒ ▒▓▒ ▒ ░ ▒▓▒ ▒ ░
░ ░ ▒ ░░ ░▒ ░ ░ ░ ▒ ▒░ ░ ░ ░▒ ░ ░ ░▒ ░ ░
░ ░ ░ ░ ░ ░ ░ ░ ▒ ░ ░ ░ ░ ░ ░ ░ ░
░ ░ ░ ░ ░ ░
"Rewritten in Rust. Faster. Safer. The same cyberpunk soul."
// WHAT IS THIS
lsofrs — List System Open Files in Rust — v3.1.0
A Rust rewrite of lsofng, the modernized lsof diagnostic tool. Maps the invisible topology between processes and the files they hold open: regular files, directories, sockets, pipes, devices, kqueues — anything the kernel touches.
If a process has a file descriptor, lsofrs sees it.
// SCREENSHOT
// JACK IN — BUILD FROM SOURCE
Or install directly:
Install the man page:
// USAGE
Network Filters
Output Formats
Selection Combinators
// ADVANCED MODES
Top-N Dashboard (--top)
Live auto-refreshing dashboard of the top processes sorted by FD count. Like iotop for file descriptors — shows FD type distribution bars, delta tracking, and per-process breakdowns.
Controls:
| Key | Action |
|---|---|
s |
Cycle sort column (FDs→PID→USER→REG→SOCK→PIPE→OTHER→DELTA→CMD) |
r |
Reverse sort order |
+/- |
Show more/fewer processes (±5) |
1-9 |
Set refresh interval (seconds) |
</> |
Fine-adjust refresh interval (±1s) |
p |
Pause/resume data collection |
b |
Toggle distribution bar column |
d |
Toggle delta column |
?/h |
Toggle help overlay |
q/Esc/Ctrl-C |
Quit |
File Watch (--watch FILE)
Monitor who opens and closes a specific file over time. Prints timestamped +OPEN/-CLOSE events as they happen — like a lightweight inotifywait / fs_usage for a single path.
Each event shows timestamp, open/close tag, PID, user, FD, and command. When piped, prints a single snapshot and exits.
Stale FDs (--stale)
Find file descriptors pointing to deleted files — a common source of disk space leaks, zombie file handles, and security issues.
Listening Ports (--ports)
Quick "what's listening where" summary — like ss -tlnp but cross-platform (macOS + Linux).
Pipe Chain (--pipe-chain)
Trace pipe and unix socket pairs between processes — visualize the IPC topology.
Network Map (--net-map)
Group network connections by remote host — see which servers your system talks to and how many connections each has.
CSV Export (--csv)
Pure CSV output for pipelines, spreadsheets, and data analysis. RFC 4180-compliant quoting.
Process Tree (--tree)
Hierarchical process tree view with FD counts, type breakdowns, and network connection counts. Like pstree meets lsof.
Each node shows: PID, user, FD count, command name, type breakdown ([REG:12 IPv4:3 PIPE:2]), and network connection count. Notable files (sockets, pipes) are listed inline under each process.
Live Monitor (--monitor / -W)
Full-screen alternate-buffer display like top(1). Auto-refreshes with interactive controls.
Controls: s=sort, r=reverse, f=filter, p=pause, ?=help, q=quit
Follow Mode (--follow PID)
Watch a single process's FDs in real-time. New opens highlighted +NEW in green, closes -DEL in red.
FD Leak Detection (--leak-detect)
Monitors per-process FD counts over time. Flags processes with monotonically increasing FD counts.
Summary / Statistics (--summary)
Aggregate FD breakdown with bar charts, top processes, per-user totals.
Delta Highlighting (--delta)
Color-code changes between repeat iterations. New FDs in green, gone in red.
// CYBERPUNK THEME
When output goes to a TTY, lsofrs activates cyberpunk-themed column headers and ANSI coloring:
| Piped | TTY |
|---|---|
| COMMAND | PROCESS |
| PID | PRC |
| USER | H4XOR |
| TYPE | CL4SS |
| DEVICE | DEV/ICE |
| SIZE/OFF | BYT3/0FF |
| NODE | N0DE |
| NAME | T4RGET |
When piped or redirected, plain headers and no colors are used — safe for scripts.
// ARCHITECTURE
src/
├── main.rs # CLI entry point, dispatch, repeat/leak-detect loops
├── cli.rs # clap argument definitions + custom help display
├── types.rs # Core data structures (Process, OpenFile, SocketInfo, etc.)
├── darwin.rs # macOS libproc FFI — process/FD enumeration (rayon parallel)
├── linux.rs # Linux /proc filesystem — process/FD enumeration (rayon parallel)
├── freebsd.rs # FreeBSD sysctl + procfs — process/FD enumeration
├── filter.rs # Selection & filtering (PID, user, command, FD, network)
├── output.rs # Columnar & field output formatting, ANSI theming
├── json.rs # JSON serialization via serde
├── monitor.rs # Live full-screen mode (crossterm alternate screen)
├── follow.rs # Single-process FD tracking with status transitions
├── leak.rs # Circular-buffer leak detector
├── delta.rs # Iteration-diff engine for change highlighting
├── summary.rs # Aggregate statistics with bar charts
├── tree.rs # Process tree view with FD inheritance
├── top.rs # Live top-N FD dashboard with delta tracking
├── watch.rs # File watch — monitor opens/closes over time
├── stale.rs # Stale FD finder — deleted files still held open
├── ports.rs # Listening ports summary (like ss -tlnp)
├── pipe_chain.rs # Pipe/socket IPC topology between processes
├── csv_out.rs # CSV export (RFC 4180)
└── net_map.rs # Network connections grouped by remote host
lsofrs.1 # Man page (roff)
completions/
└── _lsofrs # Zsh completion function
Shell Completions
Zsh completions are provided in completions/_lsofrs. To install:
# or symlink into your fpath
# then reload
&&
Platform Support
Supports macOS/Darwin (libproc FFI), Linux (/proc filesystem), and FreeBSD (sysctl + procfs). Platform modules are gated behind #[cfg(target_os)]. Process gathering is parallelized with rayon.
Key Design Decisions
- Zero-copy FFI: Raw
repr(C)structs matched to Darwin kernel headers. No intermediate parsing. - Parallel gathering: Per-PID FD enumeration parallelized with rayon.
- Streaming output: Processes are gathered, filtered, and printed in a single pass.
- crossterm for TUI: Alternate screen buffer, raw mode, cursor control — no ncurses dependency.
- serde for JSON: Derive-based serialization, no hand-rolled escaping.
- clap for CLI: Derive-based argument parsing with full help generation.
// PERFORMANCE
Benchmarked on macOS with hyperfine (10 runs, 3 warmup, ~550 processes / ~5800 open files):
All Open Files (default)
| Tool | Mean | Min–Max | User CPU | Sys CPU |
|---|---|---|---|---|
| lsofrs (Rust) | 73 ms | 50–117 ms | 17 ms | 32 ms |
| lsof 4.91 (C) | 274 ms | 225–344 ms | 108 ms | 100 ms |
| lsofng (C) | 5630 ms | 5223–8302 ms | 109 ms | 116 ms |
| vs | Speedup |
|---|---|
| lsof (system) | 3.7x faster |
| lsofng | 76.8x faster |
Network Connections (-i TCP)
| Tool | Mean | Min–Max | User CPU | Sys CPU |
|---|---|---|---|---|
| lsofrs | 89 ms | 30–307 ms | 4 ms | 14 ms |
| lsof 4.91 | 157 ms | 105–345 ms | 69 ms | 20 ms |
| lsofng | 5246 ms | 5103–5602 ms | 70 ms | 21 ms |
| vs | Speedup |
|---|---|
| lsof | 1.8x faster |
| lsofng | 58.9x faster |
Terse Output (-t, PIDs only)
| Tool | Mean | Min–Max | User CPU | Sys CPU |
|---|---|---|---|---|
| lsofrs | 46 ms | 18–124 ms | 4 ms | 14 ms |
| lsof 4.91 | 211 ms | 139–474 ms | 53 ms | 90 ms |
| lsofng | 253 ms | 172–492 ms | 52 ms | 104 ms |
| vs | Speedup |
|---|---|
| lsof | 4.6x faster |
| lsofng | 5.5x faster |
Structured Output (-J JSON / -F field)
| Tool | Mean | Min–Max | User CPU | Sys CPU |
|---|---|---|---|---|
lsofrs -J |
126 ms | 63–223 ms | 16 ms | 36 ms |
lsof -F pcfn |
231 ms | 186–488 ms | 89 ms | 89 ms |
lsofng -J |
244 ms | 159–414 ms | 59 ms | 103 ms |
| vs | Speedup |
|---|---|
| lsof | 1.8x faster |
| lsofng | 1.9x faster |
Most wall-clock time is spent in kernel syscalls (proc_pidinfo), which are identical between implementations. The Rust version's advantage comes from zero-copy FFI, efficient memory allocation, and lower user/system CPU overhead (6.4x less user CPU than lsof, 3.1x less system CPU).
// LICENSE
MIT License — Jacob Menke
// CREDITS
Rust rewrite of lsofng by Jacob Menke, which itself is a modernized fork of the original lsof by Vic Abell.