`std.fs.cwd()` returns a stateless descriptor that changes with subsequent `setAsCwd()` calls

[rootbeer]

Zig Version

0.14.0-dev.3029+bebd8d7ff

Steps to Reproduce and Observed Behavior

I'm fixing some of Zig's Posix file tests, and they change the current working directory (CWD), so to protect subsequent tests I tried starting the test with:

    // Restore default CWD at end of test.
    const orig_cwd = try std.fs.cwd();
    defer orig_cwd.setAsCwd() catch unreachable;

I read this code as using defer to restore the current working directory to the original value after the main part of the test has completed.

However, this doesn't work (on Linux**) because the CWD returned is a stateless file descriptor that means "current working directory" (Posix's AT_FDCWD). So the code in the defer ends up being a no-op.

To capture a stateful "cwd" descriptor I can open ., and now the deferred restore works as I expect (but now I also have a real file descriptor that I have to close at some point):

    var orig_cwd = try std.fs.cwd().openDir(".", .{});
    defer orig_cwd.setAsCwd() catch unreachable;

This problem came up tangentially in #9688 and #17616 and #15592. While I can see how the current semantics of cwd() are slick and efficient (its basically the entrypoint for all relative-path file operations), this does seem like very surprising behavior to someone expecting the Dir returned from std.fs.cwd() to act like other stateful file descriptor-backed handles. If the current semantics are correct as-is, then at least the doc needs an update on cwd(). And probably on setAsCwd() to say it will transparently "update" results from earlier cwd() calls. Or remove setAsCwd()?

Here's a full test to reproduce the problem:

const std = @import("std");

test "first" {
    const orig_cwd = std.fs.cwd(); // save off CWD handle

    var orig_path_buf: [std.fs.max_path_bytes]u8 = undefined;
    const orig_path = try std.posix.getcwd(orig_path_buf[0..]);

    const pdir = try std.fs.cwd().openDir("..", .{});
    try pdir.setAsCwd(); // change CWD to something new

    // ... in a real test do something here...

    try orig_cwd.setAsCwd(); // "restore" the CWD to the original

    var after_path_buf: [std.fs.max_path_bytes]u8 = undefined;
    const after_path = try std.posix.getcwd(after_path_buf[0..]);

    try std.testing.expectEqualSlices(u8, orig_path, after_path);
}

** Windows uses windows.peb().ProcessParameters.CurrentDirectory.Handle for fs.cwd(), and I'm not sure if that has the same semantics as AT_FDCWD on Linux or if its stateful.

Expected Behavior

The test above should pass. Or the doc on cwd() should call out that its always whatever the CWD is, and is not a stable handle to the current CWD.

[rohlem]

cwd() is so weird and special that if I rewrote that part of std, personally I'd make it a different type / tagged union state.
Some things work, some things (f.e. closing) don't and are completely wrong for cwd() (can lead to seemingly-unrelated failures later).
So far for every issue the resolution has been "document that you shouldn't do that".

A different idea: Instead of a function cwd(), introduce a decl cwd.
That way users can pass .cwd where it makes sense, but they're less incentivized to make a copy (they see that it's a const (or var singleton?) decl).
(I am halfway through writing a design proposal. It would work, but idk if anyone agrees that it's better, lmk if it's a good/bad idea and I'll post it or not.)

I still think in debug modes (if std.runtime_safety),
functions that we know don't work with cwd should report this to the user (design error => via @panic).
(This might be target/os specific though.)

[e4m2]

Windows uses windows.peb().ProcessParameters.CurrentDirectory.Handle for fs.cwd(), and I'm not sure if that has the same semantics as AT_FDCWD on Linux or if its stateful.

It is indeed a stateful handle instead of a stateless pseudo handle. Unlike Unix-likes, the NT kernel I/O subsystem knows nothing of the current directory - it is a userspace concept.

However, Zig doesn't really use this handle correctly on Windows. The handle's lifetime is managed by the system, it can be closed and replaced by a new one. Zig indiscriminately "borrows" (i.e. makes a dumb copy) of this handle at the time of the fs.cwd() call without any lifetime considerations.
Existing Windows APIs avoid any issues related to this because they don't directly expose CWD relative openat()-like functionality. The handle is only ever used internally within well-delimited sections of the code (and this includes, among other things, refcounting the handle).

One way to correct this on the Zig side would be to duplicate the handle while holding the PEB lock. I believe this is more or less what a GetCurrentDirectoryHandle(PHANDLE) function would do, if such a thing were to exist. Of course this isn't currently a good solution for Zig, because it breaks almost every assumption and API contract of fs.cwd().

I think a better solution would be to introduce the concept of a CWD pseudo handle on Windows. INVALID_HANDLE_VALUE might be a good candidate to imbue with this special meaning, because it's already locked in at the ABI level as being invalid/meaningless everywhere else.
Doing this would align the CWD concept on Windows with other platforms (except maybe Wasm? I dunno about Wasm) and then, if desired, a separate fallible "non-pseudo handle" API could be introduced with stateful semantics. That would hopefully cover all possible usage scenarios without unnecessarily pessimizing and/or uglifying the common fs.cwd().openFile() case.