Module canon 

Component-wise canonicalization of guest paths (port of PRoot’s canon.c), walked on descriptors.

Every component of a guest path is looked up on the host side of its binding, relative to an O_PATH descriptor of the directory walked so far, never through a textual host path: a symlink found there is read and re-interpreted in the guest namespace, so a link to /usr/lib inside the rootfs lands in the rootfs’s /usr/lib, never the host’s. The walk starts from the descriptors Fs holds open on the root and on every binding, and ends on a Resolved: the pinned parent directory and the final name, which the handlers act on with the *at syscalls and O_NOFOLLOW. A directory the guest renames away and replaces by a symlink while a call is in flight is then seen as the symlink it is, and resolved inside the guest on a retry, instead of followed on the host by the kernel’s own walk of a stale string. Directories already resolved are kept in Fs’s cache to skip the openat next time.

Structs

Resolved

A guest path resolved inside the guest namespace.

Enums

At

Where the object a guest path names is, for the *at syscalls.

Missing 🔒

What becomes of the components after a missing intermediate one.

Constants

MAX_RESTARTS 🔒

Walks started over, after a component changed under the walk, before giving up with ELOOP.

MAX_SYMLINKS 🔒

Symlink hops allowed before giving up with ELOOP (Linux’s MAXSYMLINKS).

RETRY

Sentinel errno: the object changed between two steps of a lookup or between the lookup and the call; start over from the guest path. Never reaches a tracee: resolve and the handlers turn it into ELOOP once the restarts are used up.

Functions

append_rest 🔒

Appends the remaining components to a path without touching the host.

canonicalize

Canonicalizes an absolute guest path inside the guest namespace.

child 🔒

A Resolved for name inside the pinned directory parent.

components 🔒

The non-empty components of a path, in order.

cstr 🔒

Builds a C string from path bytes.

fd_path

/proc/self/fd/<n> of a descriptor, as a C string.

follow 🔒

Re-enters a symlink target into the walk, interpreted in the guest namespace relative to the canonical directory that holds the link.

fstat_mode 🔒

st_mode of an open descriptor.

fstatat_mode 🔒

st_mode of name inside dir without following a final symlink.

is_proc_fd_link 🔒

Whether a canonical guest path is a /proc/<pid>[/task/<tid>]/fd/N or map_files/X link.

is_proc_magic_link 🔒

Whether a canonical guest path names a /proc/<pid>[/task/<tid>]/{exe,cwd,root,fd/N,map_files/X,ns/X} link.

join 🔒

Joins a canonical directory and one component.

lexical_clean

Removes . components, resolves .. lexically and collapses slashes.

lstat_mode 🔒

st_mode of a host path without following a final symlink.

object 🔒

A Resolved for a pinned mount point itself.

open_at 🔒

Opens name inside dir as an O_PATH|O_CLOEXEC descriptor with extra flags.

open_dir 🔒

Opens the canonical guest directory guest from the mount point it lies under.

open_dir_component 🔒

Opens the directory comp inside dir as an O_PATH descriptor.

pop_component 🔒

Removes the last component of a canonical path; / stays /.

proc_pid 🔒

The <n> of a /proc/<n>/... path, or of /proc/<n>/task/<t>/... (then t).

read_link 🔒

readlink(2) on a host path, as bytes.

readlinkat

readlinkat(2) of name inside dir, as bytes.

resolve

Resolves an absolute guest path inside the guest namespace to the pinned directory and name to act on.

resolve_with 🔒

textual 🔒

A Resolved the kernel resolves from the textual host path.

walk 🔒

One pass of resolve; Err(RETRY) when a component changed under it.