Skip to main content

​
Function Signature

ListDirectory() -> list[str, str] | None

​
Overview

The ListDirectory() function scans all running processes on the system to identify the process consuming the most physical memory (VmRSS). It returns a list containing a formatted description string and the process ID (PID) as a string of the memory-intensive process.
Despite its name, this function analyzes process memory usage rather than listing directory contents. It operates by scanning the /proc filesystem to examine each running process’s memory statistics.

​
Return Value

​
return
list[str, str] | None
Returns a list with two elements:
​
[0]
str
A formatted description string containing:
  • Process name
  • Process ID (PID)
  • VmRSS value in kilobytes
Format:
El proceso con mayor VmRSS es 
 Name: {process_name}
 PID: {pid}
 VmRSS: {vmrss} kB
​
[1]
str
The PID of the process as a string
Returns None if no processes can be analyzed (rare edge case).

​
How It Works

​
Process Discovery

  1. Scans /proc directory: Lists all entries in /proc
  2. Filters for PIDs: Identifies numeric directories (each represents a running process)
  3. Iterates through processes: Examines each process’s status file

​
Memory Analysis

For each process, the function:
  1. Opens /proc/{pid}/status: Reads the process status file
  2. Extracts process name: Parses the Name: field
  3. Reads VmRSS value: Extracts the VmRSS: field (Resident Set Size)
  4. Tracks maximum: Keeps track of the process with the highest VmRSS
VmRSS (Resident Set Size) represents the portion of memory occupied by a process that is held in RAM. This is “real” physical memory usage, excluding swapped-out memory pages.

​
Error Handling

The function gracefully handles two common exceptions:
  • FileNotFoundError: Process terminated between directory listing and status file read
  • PermissionError: Insufficient permissions to read certain process information (common for system processes)
These exceptions are caught and the function continues to the next process without interruption.

​
Example Output

El proceso con mayor VmRSS es 
 Name: chrome
 PID: 12345
 VmRSS: 2048576 kB

​
Usage Example

from process_analyzer import ListDirectory

# Find the process with highest memory usage
result = ListDirectory()

if result:
    description, pid = result
    print(description)
    print(f"\nProcess ID: {pid}")
else:
    print("No processes found")

​
Source Code Reference

The implementation can be found in process_analyzer.py:4-27.
The function returns a list (not a tuple) with the second element being a string representation of the PID. To use the PID as an integer, convert it: int(pid).

​
Technical Notes

​
VmRSS vs Other Memory Metrics

  • VmRSS (Resident Set Size): Physical memory actually used (what this function reports)
  • VmSize: Total virtual memory allocated (can be larger than physical RAM)
  • VmData: Size of data segment
  • VmStk: Size of stack
VmRSS is typically the most useful metric for understanding actual memory pressure on the system.

​
Permissions

Some process information may not be accessible without elevated privileges. The function handles this gracefully by skipping processes it cannot read.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us