From 12fc6883702b2379854e06c2126f6a86d62c0c73 Mon Sep 17 00:00:00 2001 From: Jan Philipp Hafer Date: Fri, 25 Feb 2022 13:48:08 +0100 Subject: [PATCH] Description and assumptions for `resolve` functions and `realpath` * doc `realpath`: specify requirements and hint to get dir of file * doc `resolve`: behavior difference on Windows and Linux + consequence --- lib/std/fs/path.zig | 4 ++++ lib/std/os.zig | 8 ++++++-- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/lib/std/fs/path.zig b/lib/std/fs/path.zig index bdd1c53ed5df..838050973ef6 100644 --- a/lib/std/fs/path.zig +++ b/lib/std/fs/path.zig @@ -468,6 +468,10 @@ fn asciiEqlIgnoreCase(s1: []const u8, s2: []const u8) bool { } /// On Windows, this calls `resolveWindows` and on POSIX it calls `resolvePosix`. +/// Note: Symlinks currently dont work and should not be used, +/// because Windows and Posix having different behavior. +/// On Windows, symlinks are resolved after `..` is resolved. +/// On POSIX, symlinks are resolved eagerly. pub fn resolve(allocator: Allocator, paths: []const []const u8) ![]u8 { if (native_os == .windows) { return resolveWindows(allocator, paths); diff --git a/lib/std/os.zig b/lib/std/os.zig index 241c38dedffd..d8e42878805e 100644 --- a/lib/std/os.zig +++ b/lib/std/os.zig @@ -1438,7 +1438,7 @@ var wasi_cwd = if (builtin.os.tag == .wasi and !builtin.link_libc) struct { /// Note that `cwd_init` corresponds to a Preopen directory, not necessarily /// a POSIX path. For example, "." matches a Preopen provided with `--dir=.` /// -/// This must be called before using any relative or absolute paths with `std.os` +/// This must be called before using any relative or absolute paths with `std.os` /// functions, if you are on WASI without linking libc. /// /// `alloc` must not be a temporary or leak-detecting allocator, since `std.os` @@ -1472,7 +1472,7 @@ pub fn initPreopensWasi(alloc: Allocator, cwd_init: ?[]const u8) !void { /// Resolve a relative or absolute path to an handle (`fd_t`) and a relative subpath. /// -/// For absolute paths, this automatically searches among available Preopens to find +/// For absolute paths, this automatically searches among available Preopens to find /// a match. For relative paths, it uses the "emulated" CWD. pub fn resolvePathWasi(path: []const u8, out_buffer: *[MAX_PATH_BYTES]u8) !RelativePathWasi { // Note: Due to WASI's "sandboxed" file handles, operations with this RelativePathWasi @@ -5091,6 +5091,10 @@ pub const RealPathError = error{ /// extra `/` characters in `pathname`. /// The return value is a slice of `out_buffer`, but not necessarily from the beginning. /// See also `realpathZ` and `realpathW`. +/// Note: All /-separated components of the supplied path must resolve to a +/// directory, or a symlink to a directory, except for the last component +/// Use `fs.path.resolve` or `fs.path.relative` to get dir of file (`file/..`). +/// assume: if relative path used, then they are relative to `getcwd()` pub fn realpath(pathname: []const u8, out_buffer: *[MAX_PATH_BYTES]u8) RealPathError![]u8 { if (builtin.os.tag == .windows) { const pathname_w = try windows.sliceToPrefixedFileW(pathname);