4.3 KiB
hss_find_pids
Source: hss-proc.h:27
Note: This function only runs when the target is local (
localhost,127.0.0.1, or one of the machine's own IPs). For remote targets,hssskips process lookup entirely and reportsusers:(("n/a",pid=0)).
Finds the process(es) that own a given listening port, using heuristic command-line matching against the Mach proc server.
Signature
static void hss_find_pids(process_t proc, int port, char *out, size_t len, int max_procs);
| Parameter | Description |
|---|---|
proc |
Mach port handle to the process server (from getproc()) |
port |
The port number to match against |
out |
Output buffer for the formatted result string |
len |
Size of out |
max_procs |
Max processes to list; 0 means unlimited |
Phase 1: Setup
char buf[256] = "", needle[16];
snprintf(needle, sizeof(needle), "%d", port);
Builds the search token — port formatted as a string (e.g., "80").
Passed to the matcher to check whether a process's command line mentions
this port.
Phase 2: Get all PIDs from the proc server
if (proc_getallpids(proc, &pids, &num_pids) != 0) {
snprintf(out, len, "users:((\"unknown\",pid=0))");
return;
}
A Mach RPC to the proc server. pids comes back as an out-of-line
array — fresh pages mapped into this task by the IPC. Failure falls back
to ss's "users:(("unknown",pid=0))" placeholder format.
Phase 3: Loop over PIDs, fetch and flatten argv
for (size_t i = 0; i < num_pids; i++) {
char *args = NULL;
mach_msg_type_number_t args_len = 0;
if (proc_getprocargs(proc, pids[i], &args, &args_len) != 0 || !args || !args_len) continue;
for (size_t j = 0; j < args_len; j++) if (!args[j]) args[j] = ' ';
For each PID, an RPC fetches its argv. The returned buffer contains
NUL-separated argument strings (python3\0-m\0http.server\08000\0). The
inner loop flattens it — replaces every NUL with a space — so the
entire command line becomes one searchable string:
python3 -m http.server 8000. Now strstr can scan it naively.
Each iteration also vm_deallocates its own args buffer (Phase 5).
Phase 4: Heuristic match
if (hss_match_process(port, args, needle)) {
Delegated to hss_match_process (hss-proc.h:19), which encodes two
strategies:
- Known services —
sshd→22,httpd/apache/nginx/lighttpd→80/443,postgres→5432,mysql/mariadb→3306,redis→6379,ftp→21 - Interpreters —
python/node/java/rubyand the port appears as a whole token in the command line (thehss_match_port_tokenboundary check prevents8000from matching inside18000)
This is the "heuristic" in Heuristic Socket Stat — best-effort attribution, not a socket table lookup.
Phase 5: Limit, extract basename, accumulate output
if (max_procs > 0 && matches >= max_procs) {
snprintf(buf + off, sizeof(buf) - off, ",+more");
vm_deallocate(mach_task_self(), (vm_address_t)args, args_len);
break;
}
Respects --process-limit / --all-processes. Note the vm_deallocate
before break — leaking Mach pages would accumulate fast in a tool that
RPCs once per PID. This is the "zero memory leaks" guarantee.
char *base = strrchr(args, '/'), *space;
base = base ? base + 1 : args;
if ((space = strchr(base, ' '))) *space = '\0';
off += snprintf(buf + off, sizeof(buf) - off,
"%s(\"%.40s\",pid=%d)", matches ? "," : "", base, pids[i]);
Extracts the basename of the executable (/usr/sbin/sshd → sshd),
truncates at the first space to drop arguments, and appends
("name",pid=N) to the accumulating buffer — exactly ss's
users:(("name",pid=N)) format.
Phase 6: Cleanup and final output
if (pids && num_pids)
vm_deallocate(mach_task_self(), (vm_address_t)pids, num_pids * sizeof(pid_t));
if (matches)
snprintf(out, len, "users:(%s)", buf);
else
snprintf(out, len, "users:((\"unknown\",pid=0))");
Frees the PID array (Mach out-of-line pages again), then emits either the collected matches or the unknown placeholder.
Output format
users:(("sshd-session",pid=13635),("python3",pid=14434))
Mirrors ss -p output so Hurd admins can use the same mental model they
know from Linux.