Expand description
sysprims-proc: Process inspection and enumeration utilities
This crate provides cross-platform process inspection capabilities with a stable JSON schema for automation. It supports listing all processes, filtering by various criteria, and getting details for a specific PID.
§Features
- Process enumeration: List all running processes
- Process inspection: Get details for a single process by PID
- Filtering: Filter by name, state, CPU, memory, user
- Stable JSON output: Schema-versioned output for automation
§Platform Support
| Feature | Linux | macOS | Windows |
|---|---|---|---|
| PID enumeration | /proc | proc_listpids | Toolhelp32 |
| Process info | /proc/[pid]/* | proc_pidinfo | OpenProcess |
| CPU usage | /proc/[pid]/stat | proc_pidinfo | GetProcessTimes |
| Memory usage | /proc/[pid]/statm | proc_pidinfo | GetProcessMemoryInfo |
§Examples
use sysprims_proc::{snapshot, get_process, ProcessFilter};
// Get all processes
let snap = snapshot().unwrap();
println!("Found {} processes", snap.processes.len());
// Get current process
let self_info = get_process(std::process::id()).unwrap();
println!("Current process: {} (PID {})", self_info.name, self_info.pid);
// Filter processes by name
let filter = ProcessFilter {
name_contains: Some("rust".into()),
..Default::default()
};
let filtered = sysprims_proc::snapshot_filtered(&filter).unwrap();Modules§
- observation
- Read-only
native-process-observation:v0OS collectors and continuity handles. Read-only OS collectors and private continuity handles forurn:3leaps:identity-evidence:native-process-observation:v0.
Structs§
- Ancestors
Result - Result of an ancestors traversal.
- Descendants
Config - Configuration for descendants traversal.
- Descendants
Level - A single level in a descendants result.
- Descendants
Result - Result of a descendants traversal.
- FdFilter
- Filter for fd queries.
- FdInfo
- Information about a single file descriptor.
- FdSnapshot
- Snapshot of open file descriptors for a process.
- Guard
Config - Configuration for one guard evaluation cycle.
- Guard
Event - Structured output for one guard evaluation cycle.
- Guard
Rule - Rule configuration for one guard evaluation cycle.
- Guard
Runner - Managed guard loop with signal handling and drift-free scheduling.
- Guard
Runner Config - Configuration for a managed guard loop.
- Guard
Runner Summary - Summary returned after a guard loop completes.
- Guard
Stop Handle - Cloneable, thread-safe handle for stopping a running guard loop.
- Port
Binding - Listening socket binding information.
- Port
Bindings Snapshot - Snapshot of listening ports at a point in time.
- Port
Filter - Filter for port queries.
- Process
Filter - Filter for process queries.
- Process
Handle - Re-exported process-bound signal and exit-watch handle (
ProcessHandle) fromsysprims-signal. A signal and exit-watch handle bound to a verified process incarnation. - Process
Info - Information about a single process.
- Process
Options - Options controlling optional process detail collection.
- Process
Snapshot - Snapshot of all processes at a point in time.
- Wait
PidResult - Result of waiting for a PID to exit.
Enums§
- CpuMode
- CPU measurement mode for descendants traversal.
- FdKind
- File descriptor kind.
- Guard
Action - Action configuration for one guard evaluation cycle.
- Guard
Preset - Preset configurations for common guard use cases.
- Process
State - Process state.
- Protocol
- Protocol for a socket binding.
- Signal
Binding - Re-exported process-bound signal and exit-watch handle (
ProcessHandle) fromsysprims-signal. How tightly signal delivery on aProcessHandleis bound to the target process incarnation. - Stop
Reason - Why the guard loop stopped.
Functions§
- ancestors
- Walk the parent chain from
pidupward, collecting process info at each step. - cpu_
total_ time_ ns - Get total CPU time consumed by a process (kernel + user) in nanoseconds.
- descendants
- Get descendants of a process using BFS traversal.
- descendants_
with_ config - Get descendants using explicit traversal configuration.
- descendants_
with_ config_ and_ options - Get descendants using explicit traversal configuration and optional extended fields.
- descendants_
with_ options - Get descendants of a process using BFS traversal with optional extended fields.
- get_
process - Get information for a single process.
- get_
process_ with_ options - Get information for a single process with optional extended fields.
- guard_
step - Execute one guard evaluation cycle.
- is_
fully_ gone - Report whether a PID has no observable process record (fully gone).
- is_live
- Report whether a PID refers to a live (non-zombie) process.
- list_
fds - List open file descriptors for a PID.
- listening_
ports - Get a snapshot of listening ports.
- open_
process_ handle - Re-exported process-bound signal and exit-watch handle (
ProcessHandle) fromsysprims-signal. Open aProcessHandlebound to the current live process incarnation atpid. - open_
process_ handle_ verified - Re-exported process-bound signal and exit-watch handle (
ProcessHandle) fromsysprims-signal. Open aProcessHandlebound topid, requiring its native start-identity to matchexpected_start_identity. - process_
by_ port - Resolve a process by port and protocol.
- select_
descendant_ targets - Select descendant target PIDs from a traversal result.
- snapshot
- Get a snapshot of all processes.
- snapshot_
filtered - Get a snapshot with filter applied.
- snapshot_
filtered_ with_ options - Get a snapshot with filter applied and optional extended fields.
- snapshot_
with_ options - Get a snapshot of all processes with optional extended fields.
- wait_
pid - Wait for a PID to exit, up to the provided timeout.