Rename os.fdPath to os.getFdPath and make it pub

Also, ensure the docs clearly state that `os.getFdPath` and
`os.realpathat` are *not* supported on all hosts.

Author: kubkon

lib/std/fs.zig

@@ -931,7 +931,9 @@ pub const Dir = struct {
         return self.openDir(sub_path, open_dir_options);
     }
 
-    /// This function behaves differently on different hosts.
+    /// This function behaves differently on different hosts, and since it uses `std.os.getFdPath`
+    /// underneath, it is not universally supported on all hosts.
+    /// Currently supported hosts are: Linux, macOS, Windows, and WASI.
     /// In WASI, returns the canonicalized relative pathname of `pathname` relative
     /// to this `Dir`. If `pathname` is absolute, or an attempt is made at
     /// escaping beyond this `Dir`, return `error.AccessDenied`.

lib/std/os.zig

@@ -3985,7 +3985,7 @@ pub const realpathC = @compileError("deprecated: renamed realpathZ");
 /// This function is very host-specific and is not universally supported by all hosts.
 /// For example, while it generally works on Linux, macOS or Windows, it is unsupported
 /// on FreeBSD, or WASI.
-fn fdPath(fd: fd_t, out_buffer: *[MAX_PATH_BYTES]u8) RealPathError![]u8 {
+fn getFdPath(fd: fd_t, out_buffer: *[MAX_PATH_BYTES]u8) RealPathError![]u8 {
     switch (builtin.os.tag) {
         .windows => {
             var wide_buf: [windows.PATH_MAX_WIDE]u16 = undefined;
@@ -4037,7 +4037,7 @@ pub fn realpathZ(pathname: [*:0]const u8, out_buffer: *[MAX_PATH_BYTES]u8) RealP
         };
         defer close(fd);
 
-        return fdPath(fd, out_buffer);
+        return getFdPath(fd, out_buffer);
     }
     const result_path = std.c.realpath(pathname, out_buffer) orelse switch (std.c._errno().*) {
         EINVAL => unreachable,
@@ -4069,14 +4069,19 @@ pub fn realpathW(pathname: [*:0]const u16, out_buffer: *[MAX_PATH_BYTES]u8) Real
     );
     defer windows.CloseHandle(h_file);
 
-    return fdPath(h_file, out_buffer);
+    return getFdPath(h_file, out_buffer);
 }
 
-/// This function will depend differently on different hosts.
-/// In WASI, it calls `realpathatWasi` which observes WASI capability-oriented
-/// security model and returns `error.AccessDenied` if the `pathname` is absolute
-/// or an attempt is made at escaping beyond the input `fd` file descriptor.
-/// On all other hosts, this function is similar to `realpath`, however, returns
+/// This function will depend differently on different hosts. Since underneath it
+/// uses `getFdPath` (with the exception of WASI) to query the host for a true
+/// canonical path to handle `fd`, this function, much like `getFdPath` is not universally
+/// supported on all hosts.
+/// Currently, the supported hosts are: Linux, macOS, Windows, and WASI.
+/// In WASI, it does not issue any `getFdPath`-like calls. Instead, it canonicalizes
+/// the input path `pathname` upto the handle `fd` while observing WASI capability-oriented
+/// security model. If `pathname` is absolute, return `error.AbsolutePath`. See `realpathatWasi`
+/// for more information on how it works in WASI.
+/// On all other supported hosts, this function is similar to `realpath`, however, returns
 /// the canonicalized absolute pathname of a `pathname` relative to a file descriptor
 /// `fd`. If `pathname` is an absolute path, ignores `fd` and reverts to calling
 /// `realpath` on the `pathname` argument. In particular, on Unix, if `fd` was
@@ -4119,7 +4124,7 @@ pub fn realpathatZ(fd: fd_t, pathname: [*:0]const u8, out_buffer: *[MAX_PATH_BYT
             };
         };
     } else {
-        fd_path = try fdPath(fd, &buffer);
+        fd_path = try getFdPath(fd, &buffer);
     }
 
     const total_len = fd_path.len + mem.lenZ(pathname) + 1; // +1 to account for path separator
@@ -4145,7 +4150,7 @@ pub fn realpathatW(fd: fd_t, pathname: [*:0]const u16, out_buffer: *[MAX_PATH_BY
     }
 
     var buffer: [MAX_PATH_BYTES]u8 = undefined;
-    const fd_path = try fdPath(fd, &buffer);
+    const fd_path = try getFdPath(fd, &buffer);
 
     // Convert UTF16LE to UTF8
     var pathname_u8: [MAX_PATH_BYTES]u8 = undefined;