lsof

Documentation

Overview

Package lsof implements the lsof builtin command.

lsof — list open files, with emphasis on deleted-but-still-open files

Usage: lsof [-p PIDLIST] [-c NAME] [-u UIDLIST] [-a] [-h] [--help]

Display open file descriptors across processes: numeric fds plus the cwd/rtd (root)/txt (executable) special descriptors. A file that has been unlinked while a process still holds it open is reported with a " (deleted)" suffix on NAME — the primary diagnostic this builtin exists for (e.g. explaining "disk full but du shows nothing").

File descriptor enumeration is delegated to the internal procfd package, which reads /proc/<pid>/fd/* on Linux. The /proc read itself is exempt from the AllowedPaths sandbox for the same reason ss/ip route/df/free are: the paths are hardcoded, never derived from user input. However, unlike those commands, the resolved filesystem path shown in the NAME column IS checked against AllowedPaths: a path outside every configured root is replaced with "(restricted)" (or "(restricted) (deleted)"), and its DEVICE/SIZE/NODE columns are blanked alongside it, since those are per-file attributes tied to the same out-of-sandbox path (an exact byte count, device number, and inode would otherwise still fingerprint a specific restricted file even with NAME hidden). This is a deliberate divergence, made because NAME can point anywhere on the host filesystem, unlike the bounded kernel counters ss/df/free expose. With no AllowedPaths configured, every NAME is restricted (see builtins/help/help.go's "no allowed paths configured" message: an empty list means no filesystem paths are reachable, not "unrestricted"). Sockets, pipes, and anonymous inodes are never real filesystem paths and are therefore never gated.

Linux only; macOS and Windows exit 1 with "not supported on this platform" (see the free builtin for the same pattern and rationale).

Accepted flags:

-p PIDLIST
    Select processes by comma- or space-separated PID list.

-c NAME
    Select processes whose command name has this literal prefix
    (no regex, no globbing).

-u UIDLIST
    Select processes by comma- or space-separated numeric UID list.
    Login-name resolution is out of scope (no /etc/passwd read);
    only numeric UIDs are accepted, matching the ps builtin's UID
    column.

-a
    AND the selection criteria above instead of the default OR.
    Has no effect when zero or one selector is given.

-h, --help
    Print usage to stdout and exit 0.

Output columns:

COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME

SIZE/OFF reports the file's size in bytes, not its read/write offset (real lsof can show either, selected by flags this builtin does not implement); size is what serves the deleted-open-file diagnostic this tool targets.

Rejected flags (intentionally not registered; rejected as unknown by pflag with exit 1): -i/-U/-s/-T/-n/-P (network detail, already covered by ss), +d/+D (unbounded directory-tree stat scans), +|-r (repeat mode), -D/-f/+f (persistent device-number cache files — builtins must not write files outside remediation capabilities), -g/-G/-v/-V/-w/-x/-X/-C/-o/-b/ -e/-A/-k/-K/-z/-Z.

Exit codes:

0  Success, including when zero files match with no selector given.
1  Unsupported platform, invalid flag value, extra operand, a
   selector matched zero files, or an OS error listing processes.

Index

• Variables

Variables

var Cmd = builtins.Command{
	Name:        "lsof",
	Description: "list open files",
	MakeFlags:   registerFlags,
}

Cmd is the lsof builtin command descriptor.