SerenityOS realpath 命令完全指南：从符号链接解析到内核路径解析原理

导读

本文围绕 SerenityOS 用户态工具 realpath 展开，完整讲解其命令行语法、选项、退出码与典型用法，并沿用户态到内核态的调用链深入剖析路径解析（path resolution）的底层实现，包括符号链接追踪、.. 回溯、挂载点切换与 ELOOP 保护等机制。读完本文，你既能熟练使用 realpath 在 Shell 中解析出文件系统的"真实路径"，也能理解 SerenityOS 中 realpath 系统调用与 VFS 路径解析器的内部工作原理。

命令概览：什么是 realpath

realpath 是一个输出文件"真实路径"（real path）的命令行工具。所谓真实路径，是指沿着给定路径逐级解析所有符号链接（symbolic link）之后得到的、不包含任何链接成分的绝对路径。

在 SerenityOS 中，该工具的手册页位于 Base/usr/share/man/man1/realpath.md，其实现源码位于 Userland/Utilities/realpath.cpp。它的典型应用场景包括：

• 定位一个符号链接最终指向的实际文件，例如 realpath /bin 输出 /bin 链接背后的真实目录；
• 将相对路径（如 ../foo、./bar）规范化为绝对路径；
• 在脚本中判断两个路径是否最终指向同一个文件。

语法与参数

根据手册页，realpath 的命令行语法为：

$ realpath [options] <paths>

关键点在于 <paths> 是一个位置参数（positional argument），且可以一次传入多个路径。源码 Userland/Utilities/realpath.cpp 中的定义如下：

args_parser.add_positional_argument(paths, "Path to resolve", "paths");

对应的参数类型为 Vector<StringView>，因此程序会循环处理每一个路径并分别输出结果（realpath.cpp）：

for (auto path : paths) {
    auto resolved_path_or_error = FileSystem::real_path(path);
    if (resolved_path_or_error.is_error()) {
        if (!quiet)
            warnln("realpath: {}: {}", path, strerror(resolved_path_or_error.error().code()));
        has_errors = true;
        continue;
    }
    outln("{}", resolved_path_or_error.release_value());
}

参数说明

参数	含义	说明
paths	要解析的路径	可传一个或多个；支持绝对路径、相对路径、含 ../. 的路径以及符号链接路径

每个成功解析的路径会独占一行输出到标准输出（outln）；解析失败的路径会向标准错误输出一条 realpath: <path>: <错误原因> 格式的错误信息，并继续处理下一个路径。

选项详解

手册页中只定义了一个选项：

短选项	长选项	说明
-q	--quiet	静默模式：抑制（抑制）错误信息输出

其源码定义见 Userland/Utilities/realpath.cpp：

args_parser.add_option(quiet, "Suppress error messages", "quiet", 'q');

在 -q 模式下，当某个路径解析失败时（例如路径不存在、无权限访问中间目录），程序仍然会返回非零退出码，但不会打印错误信息，便于在脚本中对"路径是否存在"做静默探测。例如：

$ realpath /nonexistent/path
realpath: /nonexistent/path: No such file or directory
$ realpath -q /nonexistent/path
$ echo $?
1

退出码语义

从 Userland/Utilities/realpath.cpp 的返回值逻辑可以看出：

• 0：所有传入的路径都成功解析；
• 1：至少有一个路径解析失败（无论是否使用 -q）。

这一行为与"多个路径逐个处理、失败即标记"的设计一致：has_errors 一旦置位，最终返回码即为 1，但程序不会在第一个失败路径处中止，而是继续处理剩余路径。

权限模型：pledge 声明

SerenityOS 对用户态程序实行 pledge 能力限制。realpath 在入口处声明了它所需的最小权限集合（Userland/Utilities/realpath.cpp）：

TRY(Core::System::pledge("stdio rpath"));

• stdio：允许标准输入输出操作（打印结果与错误信息）；
• rpath：允许只读路径解析类操作，对应内核侧 realpath 系统调用对 Pledge::rpath 的校验（见 Kernel/Syscalls/realpath.cpp）。

也就是说，realpath 是一个纯粹的只读查询工具，不涉及任何写操作或网络操作。

底层实现：从用户态到内核态

realpath 的核心逻辑并不在工具源码中，而是封装在库函数与内核系统调用里。整个调用链如下：

realpath 工具（Userland/Utilities/realpath.cpp）
  └─> LibFileSystem::FileSystem::real_path()
        └─> libc realpath(path, nullptr)
              └─> 内核 sys$realpath（Kernel/Syscalls/realpath.cpp）
                    └─> VirtualFileSystem::resolve_path()
                          └─> Custody::try_serialize_absolute_path()

1. LibFileSystem 层的封装

用户态库 Userland/Libraries/LibFileSystem/FileSystem.cpp 中的 FileSystem::real_path() 是对 libc realpath() 的封装：

ErrorOr<ByteString> real_path(StringView path)
{
    if (path.is_null())
        return Error::from_errno(ENOENT);

    ByteString dep_path = path;
    char* real_path = realpath(dep_path.characters(), nullptr);
    ScopeGuard free_path = [real_path]() { free(real_path); };

    if (!real_path)
        return Error::from_syscall("realpath"sv, -errno);

    return ByteString { real_path, strlen(real_path) };
}

两个值得注意的实现细节：

• 缓冲区由库分配：realpath() 的第二个参数传 nullptr，表示由 libc 动态分配足够容纳结果的缓冲区，使用完毕后通过 ScopeGuard 自动 free，避免调用者手工管理内存；
• 错误传递：realpath() 返回空指针时，将 errno 包装为 Error::from_syscall 返回，工具层再通过 strerror 还原为可读的错误文本。

2. 内核系统调用 sys$realpath

内核侧实现位于 Kernel/Syscalls/realpath.cpp。它首先校验 pledge 承诺，然后把用户传入的路径交给 VFS 解析：

auto path = TRY(get_syscall_path_argument(params.path));
auto custody = TRY(VirtualFileSystem::resolve_path(vfs_root_context(), credentials(), path->view(), current_directory()));
auto absolute_path = TRY(custody->try_serialize_absolute_path());

这里出现了 SerenityOS 文件系统层的一个核心抽象：Custody（"监护"对象）。它封装了"路径组件 → inode"的绑定关系，并持有指向父 Custody 的指针，从而构成一条从当前节点到根节点的链。resolve_path 完成后返回的是目标文件对应的 Custody，而非直接的字符串。

3. Custody 链与绝对路径序列化

Custody::try_serialize_absolute_path()（Kernel/FileSystem/Custody.cpp）沿着 parent 指针一路回溯到根节点，逆序拼接各层名字，最终得到形如 /home/anon/foo 的绝对路径：

Vector<Custody const*, 32> custody_chain;
size_t path_length = 0;
for (auto const* custody = this; custody; custody = custody->parent()) {
    TRY(custody_chain.try_append(custody));
    path_length += custody->m_name->length() + 1;
}
// ... 逆序写入 '/' 与各组件名 ...

正因如此，realpath 的输出天然是规范化的绝对路径：不包含 .、..，也不包含符号链接成分。

内核路径解析的详细流程

路径解析的核心实现在 Kernel/FileSystem/VirtualFileSystem.cpp 的 resolve_path_without_veil()，它是一个逐组件（component-wise）的解析器，realpath 的语义正是由它决定的。

起点与递归保护

if (symlink_recursion_level >= symlink_recursion_limit)
    return ELOOP;

每次追踪符号链接都会使递归层级加一，超过 symlink_recursion_limit 后返回 ELOOP，防止出现环形链接（如 a -> b、b -> a）导致无限递归。这也解释了为什么对环形符号链接执行 realpath 会报 Too many levels of symbolic links。

逐组件遍历

解析器使用 GenericLexer 按 / 切分路径，并维护一个"当前 Custody"游标（VirtualFileSystem.cpp）：

NonnullRefPtr<Custody> custody = path[0] == '/' ? vfs_root_context_custody : base;

• 绝对路径从 VFS 根 Custody 出发；
• 相对路径以 current_directory() 为基准（这也是 sys$realpath 传入 current_directory() 的原因）。

每进入一个组件，都会检查父目录的元数据（VirtualFileSystem.cpp）：

auto parent_metadata = parent.inode().metadata();
if (!parent_metadata.is_directory())
    return ENOTDIR;
if (!parent_metadata.may_execute(credentials))
    return EACCES;

即：路径中间任何组件若不是目录则返回 ENOTDIR；用户对中间目录没有执行（搜索）权限则返回 EACCES。因此 realpath 对不可达路径会如实报错，而非只做词法替换。

. 与 .. 的处理

if (part == "..") {
    // If we encounter a "..", take a step back, but don't go beyond the root.
    if (custody->parent())
        custody = *custody->parent();
    continue;
} else if (part == "." || part.is_empty()) {
    continue;
}

• .. 在 Custody 链上向上移动一层，但不会越过根节点；
• . 与空组件（连续斜杠）被直接跳过。

注意：这里对 .. 的处理发生在符号链接解析之后的语义层面，与纯文本层面的 .. 消除（见下文"与词法规范化的区别"）不同。

符号链接的追踪与安全校验

当子组件是一个符号链接时（VirtualFileSystem.cpp），解析器会：

1. 若当前已是最后一个组件且请求了 O_NOFOLLOW，则直接返回 ELOOP；
2. 调用 safe_to_follow_symlink()（VirtualFileSystem.cpp）做安全校验：对于位于 sticky 且全局可写 目录（如 /tmp）中的符号链接，只有当链接所有者与目录所有者一致时才允许跟随，这是针对"目录内符号链接劫持"类攻击的防护；
3. 解析链接目标 resolve_as_link，剩余路径相对链接目标继续递归解析。

挂载点切换

在查找子节点后，解析器会查询该 Custody 上是否挂载了其他文件系统（VirtualFileSystem.cpp）：

auto found_mount_state_or_error = vfs_root_context.current_mount_state_for_host_custody(current_custody);
if (!found_mount_state_or_error.is_error()) {
    auto found_mount_state = found_mount_state_or_error.release_value();
    child_inode = found_mount_state.details.guest;
    ...
}

如果某路径组件是挂载点，解析会切换到被挂载文件系统的根 inode（guest inode）。这意味着 realpath 能正确穿透挂载边界，返回的是挂载后的真实文件系统视图中的路径，而不是底层文件系统的路径。

与 stat 类系统调用的对比

值得注意的是，resolve_path 同样被 stat、chmod、open、mkdir 等大量系统调用复用（参见 Kernel/FileSystem/VirtualFileSystem.cpp 中 open、unlink、rename、symlink 等实现对它的调用），因此 realpath 解析出的路径语义与这些系统调用最终访问的文件完全一致。这保证了"realpath 的输出可以直接用于后续文件操作"这一实用性质。

realpath 与词法规范化的区别

SerenityOS 的 AK::LexicalPath 提供了**纯词法（lexical）**的路径规范化函数 AK/LexicalPath.cpp canonicalized_path()：

for (auto& part : parts) {
    if (part == ".")
        continue;
    if (part == "..") {
        if (canonical_parts.is_empty()) { ... }
        else {
            if (canonical_parts.last() != "..") {
                canonical_parts.take_last(); // 相互抵消
                continue;
            }
        }
    }
    canonical_parts.append(part);
}

两者有本质区别，需要明确区分：

维度	realpath（真实路径）	LexicalPath::canonicalized_path（词法规范化）
是否访问文件系统	是，逐组件进行 inode 查找	否，纯字符串处理
符号链接	全部解析（可能触发 ELOOP）	不解析，视为普通组件
. / ..	在 Custody 链上移动	词法消除/抵消
路径不存在时	报错（ENOENT 等）	仍返回规范化字符串
路径存在性验证	隐含验证所有中间目录可搜索	不验证

实践中：realpath 用于确认文件真实存在并拿到其真实位置；词法规范化（对应 FileSystem::absolute_path 在文件不存在时的回退分支，见 Userland/Libraries/LibFileSystem/FileSystem.cpp）则用于纯路径字符串整理。例如 LexicalPath::canonicalized_path("/a/./b/../c") 直接得到 /a/c，而 realpath 会要求 /a/b 真实存在才能完成解析。

使用示例

以下示例基于 SerenityOS Shell（其手册页同样位于 Base/usr/share/man 目录体系中）：

解析单个路径：

$ realpath /home/anon
/home/anon

解析相对路径为绝对路径：

$ cd /home/anon
$ realpath ../anon/./Documents
/home/anon/Documents

一次解析多个路径（各自独立输出）：

$ realpath /bin /home/anon
/bin/Shell
/home/anon

静默探测路径是否存在（常用于脚本条件判断）：

$ if realpath -q /etc/issue >/dev/null; then
>     echo "found"
> fi
found

通过符号链接链解析最终目标：

$ ln -s /home/anon/notes.txt /tmp/note-link
$ realpath /tmp/note-link
/home/anon/notes.txt

相关源码与文档索引

• 手册页：Base/usr/share/man/man1/realpath.md
• 工具实现：Userland/Utilities/realpath.cpp
• 用户态路径封装：Userland/Libraries/LibFileSystem/FileSystem.cpp
• 内核系统调用：Kernel/Syscalls/realpath.cpp
• VFS 路径解析器：Kernel/FileSystem/VirtualFileSystem.cpp
• Custody 绝对路径序列化：Kernel/FileSystem/Custody.cpp
• 词法规范化对照实现：AK/LexicalPath.cpp

通过本文的纵向梳理可以看到，一个看似简单的 realpath 命令背后，是 SerenityOS "pledge 最小权限 + 用户态库封装 + 内核 VFS 逐组件解析 + Custody 链回溯"这一完整链路的设计体现。理解这条链路，也就理解了 SerenityOS 文件系统路径解析的核心模型。