ziglang/zig

Fork 558

Encountered `std.posix.UnexpectedError` reading certain symlinks on Windows #30164

New issue

Closed

opened 2025-12-10 19:13:25 +01:00 by thanood · 6 comments

thanood commented

2025-12-10 19:13:25 +01:00

Zig Version

0.16.0-dev.1484+d0ba6642b

Steps to Reproduce and Observed Output

I'm not sure if this fits the "improve error message" template or if it's a bug report.

While iterating a directory on Windows, I've noticed that certain symlinks of directories don't show up as symlinks but as directories itself when reading entry.kind.

An example:

    const iterable = try std.fs.cwd().openDir(".", .{ .iterate = true });
    var iter = iterable.iterate();

    const expected_num_symlinks = 0;
    var num_symlinks: usize = 0;
    while (try iter.next()) |entry| {
        std.debug.print("Name: {s}, kind: {any}\n", .{ entry.name, entry.kind });
        if (entry.kind == std.fs.File.Kind.sym_link) num_symlinks += 1;
    }

Turns out zig does not always behave this way. In fact, symlinks created by zig itself seem to be reported as symlinks correctly. Symlinks created by Powershell seem to be "different" somehow. 😃

So what's the best way to check for such symlinks? I thought maybe I should just read the symlink and eat the error NotLink.
Iterating a directory in such a way produces errors when encountering a (real) directory which is not a symlink, as expected. In theory, one can just ignore the error and move on.

Instead of throwing NotLink trying to readLink one of these directories produces std.posix.UnexpectedError and as the stdlib documentation says "When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function." - I'm here to report. 😃

I've included a reproduction zip with this issue. It contains a zig test and a PowerShell script. The zig tests executed the script which temporarily creates a directory and a symlink, which points to that directory. Please try to run it on WIndows using zig test .\symlinks.zig

It should yield something similar to:

Name: create-symlinks.ps1, kind: .file
Name: ps_dir, kind: .directory
Name: ps_dir_symlink, kind: .directory
Name: symlinks.zig, kind: .file
Name: win-symlink-repro.zip, kind: .file
link target: ps_dir
error.Unexpected NTSTATUS=0xc0000275
C:\Users\danie\AppData\Local\zig\p\N-V-__8AAGycExUKCyBnbt4_403Scw_6bJkIKSmr-oo80WTx\lib\std\os\windows.zig:372:40: 0x7ff76c5e7e21 in DeviceIoControl (test_zcu.obj)
        else => return unexpectedStatus(rc),
                                       ^
C:\Users\danie\AppData\Local\zig\p\N-V-__8AAGycExUKCyBnbt4_403Scw_6bJkIKSmr-oo80WTx\lib\std\os\windows.zig:897:24: 0x7ff76c5ce42c in ReadLink (test_zcu.obj)
    _ = DeviceIoControl(result_handle, FSCTL_GET_REPARSE_POINT, null, reparse_buf[0..]) catch |err| switch (err) {
                       ^
C:\Users\danie\AppData\Local\zig\p\N-V-__8AAGycExUKCyBnbt4_403Scw_6bJkIKSmr-oo80WTx\lib\std\fs\Dir.zig:1403:28: 0x7ff76c5ce05b in readLinkW (test_zcu.obj)
    return windows.ReadLink(self.fd, sub_path_w, buffer);
                           ^
C:\Users\danie\AppData\Local\zig\p\N-V-__8AAGycExUKCyBnbt4_403Scw_6bJkIKSmr-oo80WTx\lib\std\fs\Dir.zig:1365:44: 0x7ff76c5c49a6 in readLink (test_zcu.obj)
        const result_w = try self.readLinkW(sub_path_w.span(), &sub_path_w.data);
                                           ^
C:\Users\danie\source\repos\zig\win-symlink-repro\symlinks.zig:37:30: 0x7ff76c5c171f in test.access PowerShell symlinks (test_zcu.obj)
    _ = std.fs.cwd().readLink("ps_dir", &buf) catch |err| blk: {
                             ^
C:\Users\danie\AppData\Local\zig\p\N-V-__8AAGycExUKCyBnbt4_403Scw_6bJkIKSmr-oo80WTx\lib\compiler\test_runner.zig:248:25: 0x7ff76c696d0c in mainTerminal (test_zcu.obj)
        if (test_fn.func()) |_| {
                        ^
C:\Users\danie\AppData\Local\zig\p\N-V-__8AAGycExUKCyBnbt4_403Scw_6bJkIKSmr-oo80WTx\lib\compiler\test_runner.zig:71:28: 0x7ff76c693138 in main (test_zcu.obj)
        return mainTerminal();
                           ^
C:\Users\danie\AppData\Local\zig\p\N-V-__8AAGycExUKCyBnbt4_403Scw_6bJkIKSmr-oo80WTx\lib\std\start.zig:527:53: 0x7ff76c692c0c in WinStartup (test_zcu.obj)
    std.os.windows.ntdll.RtlExitUserProcess(callMain());
                                                    ^
???:?:?: 0x7ffc069de8d6 in ??? (KERNEL32.DLL)
???:?:?: 0x7ffc0766c53b in ??? (ntdll.dll)
error reading link: error.Unexpected
Name: create-symlinks.ps1, kind: .file
Name: symlinks.zig, kind: .file
Name: win-symlink-repro.zip, kind: .file
Name: zig_dir, kind: .directory
Name: zig_dir_symlink, kind: .sym_link
All 2 tests passed.

Expected Output

In the reproduction output above, I would expect
error reading link: error.Unexpected to say error reading link: error.NotLink.

### Zig Version 0.16.0-dev.1484+d0ba6642b ### Steps to Reproduce and Observed Output I'm not sure if this fits the "improve error message" template or if it's a bug report. While iterating a directory on Windows, I've noticed that certain symlinks of directories don't show up as symlinks but as directories itself when reading `entry.kind`. An example: ```zig const iterable = try std.fs.cwd().openDir(".", .{ .iterate = true }); var iter = iterable.iterate(); const expected_num_symlinks = 0; var num_symlinks: usize = 0; while (try iter.next()) |entry| { std.debug.print("Name: {s}, kind: {any}\n", .{ entry.name, entry.kind }); if (entry.kind == std.fs.File.Kind.sym_link) num_symlinks += 1; } ``` Turns out zig does not always behave this way. In fact, symlinks created by zig itself seem to be reported as symlinks correctly. Symlinks created by Powershell seem to be "different" somehow. 😃 So what's the best way to check for such symlinks? I thought maybe I should just read the symlink and eat the error `NotLink`. Iterating a directory in such a way produces errors when encountering a (real) directory which is not a symlink, as expected. In theory, one can just ignore the error and move on. Instead of throwing `NotLink` trying to `readLink` one of these directories produces `std.posix.UnexpectedError` and as the [stdlib documentation](https://ziglang.org/documentation/0.15.2/std/#std.posix.UnexpectedError) says "When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function." - I'm here to report. 😃 I've included a reproduction zip with this issue. It contains a zig test and a PowerShell script. The zig tests executed the script which temporarily creates a directory and a symlink, which points to that directory. Please try to run it on WIndows using `zig test .\symlinks.zig` It should yield something similar to: ``` Name: create-symlinks.ps1, kind: .file Name: ps_dir, kind: .directory Name: ps_dir_symlink, kind: .directory Name: symlinks.zig, kind: .file Name: win-symlink-repro.zip, kind: .file link target: ps_dir error.Unexpected NTSTATUS=0xc0000275 C:\Users\danie\AppData\Local\zig\p\N-V-__8AAGycExUKCyBnbt4_403Scw_6bJkIKSmr-oo80WTx\lib\std\os\windows.zig:372:40: 0x7ff76c5e7e21 in DeviceIoControl (test_zcu.obj) else => return unexpectedStatus(rc), ^ C:\Users\danie\AppData\Local\zig\p\N-V-__8AAGycExUKCyBnbt4_403Scw_6bJkIKSmr-oo80WTx\lib\std\os\windows.zig:897:24: 0x7ff76c5ce42c in ReadLink (test_zcu.obj) _ = DeviceIoControl(result_handle, FSCTL_GET_REPARSE_POINT, null, reparse_buf[0..]) catch |err| switch (err) { ^ C:\Users\danie\AppData\Local\zig\p\N-V-__8AAGycExUKCyBnbt4_403Scw_6bJkIKSmr-oo80WTx\lib\std\fs\Dir.zig:1403:28: 0x7ff76c5ce05b in readLinkW (test_zcu.obj) return windows.ReadLink(self.fd, sub_path_w, buffer); ^ C:\Users\danie\AppData\Local\zig\p\N-V-__8AAGycExUKCyBnbt4_403Scw_6bJkIKSmr-oo80WTx\lib\std\fs\Dir.zig:1365:44: 0x7ff76c5c49a6 in readLink (test_zcu.obj) const result_w = try self.readLinkW(sub_path_w.span(), &sub_path_w.data); ^ C:\Users\danie\source\repos\zig\win-symlink-repro\symlinks.zig:37:30: 0x7ff76c5c171f in test.access PowerShell symlinks (test_zcu.obj) _ = std.fs.cwd().readLink("ps_dir", &buf) catch |err| blk: { ^ C:\Users\danie\AppData\Local\zig\p\N-V-__8AAGycExUKCyBnbt4_403Scw_6bJkIKSmr-oo80WTx\lib\compiler\test_runner.zig:248:25: 0x7ff76c696d0c in mainTerminal (test_zcu.obj) if (test_fn.func()) |_| { ^ C:\Users\danie\AppData\Local\zig\p\N-V-__8AAGycExUKCyBnbt4_403Scw_6bJkIKSmr-oo80WTx\lib\compiler\test_runner.zig:71:28: 0x7ff76c693138 in main (test_zcu.obj) return mainTerminal(); ^ C:\Users\danie\AppData\Local\zig\p\N-V-__8AAGycExUKCyBnbt4_403Scw_6bJkIKSmr-oo80WTx\lib\std\start.zig:527:53: 0x7ff76c692c0c in WinStartup (test_zcu.obj) std.os.windows.ntdll.RtlExitUserProcess(callMain()); ^ ???:?:?: 0x7ffc069de8d6 in ??? (KERNEL32.DLL) ???:?:?: 0x7ffc0766c53b in ??? (ntdll.dll) error reading link: error.Unexpected Name: create-symlinks.ps1, kind: .file Name: symlinks.zig, kind: .file Name: win-symlink-repro.zip, kind: .file Name: zig_dir, kind: .directory Name: zig_dir_symlink, kind: .sym_link All 2 tests passed. ``` ### Expected Output In the reproduction output above, I would expect `error reading link: error.Unexpected` to say `error reading link: error.NotLink`.

win-symlink-repro.zip

1.1 KiB

👍 1

thanood added the

error message

label

2025-12-10 19:13:25 +01:00

thanood changed title from ~~Encountered std.posix.UnexpectedError reading certain symlinks on Windows~~ to Encountered std.posix.UnexpectedError reading certain symlinks on Windows

2025-12-10 19:18:34 +01:00

squeek502 added

bug

os/windows

and removed

error message

labels

2025-12-11 02:43:51 +01:00

squeek502 commented

2025-12-11 02:49:43 +01:00

Member

For context, NTSTATUS=0xc0000275 is NOT_A_REPARSE_POINT

For context, `NTSTATUS=0xc0000275` is `NOT_A_REPARSE_POINT`

alexrp added the

lib/std

label

2025-12-11 14:58:37 +01:00

squeek502 commented

2025-12-14 07:43:39 +01:00

Member

For the entry.kind problem:

The PowerShell-created symlink gets its kind as .directory because attrs.DIRECTORY is taking precedence over attrs.REPARSE_POINT. This seems like a mistake and is different to how stat reports kind.
The Zig-created symlink test is succeeding because you are actually creating a file symlink instead of a directory symlink. Dir.symLink takes a flags parameter with an is_directory field that needs to be set to true to create a directory symlink on Windows. If you set that flag, the test behaves the same as the PowerShell-created symlink test:

test "access zig symlinks" {
    try std.fs.cwd().makeDir("zig_dir");
    try std.fs.cwd().symLink("zig_dir", "zig_dir_symlink", .{ .is_directory = true });

    defer {
        std.fs.cwd().deleteFile("zig_dir_symlink") catch {};
        std.fs.cwd().deleteDir("zig_dir") catch {};
    }

    const iterable = try std.fs.cwd().openDir(".", .{ .iterate = true });
    var iter = iterable.iterate();

    const expected_num_symlinks = 1;
    var num_symlinks: usize = 0;
    while (try iter.next()) |entry| {
        std.debug.print("Name: {s}, kind: {any}\n", .{ entry.name, entry.kind });
        if (entry.kind == std.fs.File.Kind.sym_link) num_symlinks += 1;
    }

    try std.testing.expectEqual(expected_num_symlinks, num_symlinks);
}

For the `entry.kind` problem: - The PowerShell-created symlink gets its kind as `.directory` because [attrs.DIRECTORY is taking precedence over attrs.REPARSE_POINT](https://codeberg.org/ziglang/zig/src/commit/2f2b09757682d4c3624d8e6d470852b1d1d6264d/lib/std/fs/Dir.zig#L490-L491). This seems like a mistake and is different to how `stat` reports `kind`. - The Zig-created symlink test is succeeding because you are actually creating a file symlink instead of a directory symlink. `Dir.symLink` takes a `flags` parameter with an `is_directory` field that needs to be set to `true` to create a directory symlink on Windows. If you set that flag, the test behaves the same as the PowerShell-created symlink test: ```zig test "access zig symlinks" { try std.fs.cwd().makeDir("zig_dir"); try std.fs.cwd().symLink("zig_dir", "zig_dir_symlink", .{ .is_directory = true }); defer { std.fs.cwd().deleteFile("zig_dir_symlink") catch {}; std.fs.cwd().deleteDir("zig_dir") catch {}; } const iterable = try std.fs.cwd().openDir(".", .{ .iterate = true }); var iter = iterable.iterate(); const expected_num_symlinks = 1; var num_symlinks: usize = 0; while (try iter.next()) |entry| { std.debug.print("Name: {s}, kind: {any}\n", .{ entry.name, entry.kind }); if (entry.kind == std.fs.File.Kind.sym_link) num_symlinks += 1; } try std.testing.expectEqual(expected_num_symlinks, num_symlinks); } ```

❤️ 1

squeek502 referenced this issue

2025-12-14 08:18:40 +01:00

Windows: Avoid ever-expanding DeviceIoControl error set, handle NOT_A_REPARSE_POINT in ReadLink #30186

squeek502 referenced this issue

2025-12-14 09:31:42 +01:00

Dir.Iterator: Prioritize REPARSE_POINT over DIRECTORY when reporting kind on Windows #30188

thanood commented

2025-12-14 10:02:04 +01:00

Author

Great feedback, thanks!

The Zig-created symlink test is succeeding because you are actually creating a file symlink instead of a directory symlink.

Oh, what an oversight on my part. Thanks for pointing that out.
Also interesting that stat reports symlinks when it follows them. I'm learning a lot here. 😃

If I may ask another question..

Is this part of a test reading a directory symlink as a file then, considering O_DIRECTORY is not set?

                 .linux => linux_symlink: {
                     const sub_path_c = try posix.toPosixPath("symlink");
                     // the O_NOFOLLOW | O_PATH combination can obtain a fd to a symlink
                     // note that if O_DIRECTORY is set, then this will error with ENOTDIR
                     const flags: posix.O = .{
                         .NOFOLLOW = true,
                         .PATH = true,
                         .ACCMODE = .RDONLY,
                         .CLOEXEC = true,
                     };
                     const fd = try posix.openatZ(ctx.dir.fd, &sub_path_c, flags, 0);
                     break :linux_symlink Dir{ .fd = fd };
                 },

Great feedback, thanks! > The Zig-created symlink test is succeeding because you are actually creating a file symlink instead of a directory symlink. Oh, what an oversight on my part. Thanks for pointing that out. Also interesting that `stat` reports symlinks when it follows them. I'm learning a lot here. 😃 If I may ask another question.. Is this part of a test reading a directory symlink as a file then, considering `O_DIRECTORY` is not set? https://codeberg.org/ziglang/zig/src/commit/36cb5ea5f4c9f1a96953f30812ebaf79f8a546d6/lib/std/fs/test.zig#L340-L352

squeek502 commented

2025-12-14 10:55:14 +01:00

Member

Also interesting that stat reports symlnks when it follows them.

That's not what I meant, are you seeing that behavior locally?

I was referring to the fact that File.stat can return .sym_link if the File.handle itself pertains to a symlink, which is something you have to pretty intentionally do and isn't possible on all systems. The relevant test is here:

 test "File.stat on a File that is a symlink returns Kind.sym_link" {
     // This test requires getting a file descriptor of a symlink which
     // is not possible on all targets
     switch (builtin.target.os.tag) {
         .windows, .linux => {},
         else => return error.SkipZigTest,

> Also interesting that `stat` reports symlnks when it follows them. That's not what I meant, are you seeing that behavior locally? I was referring to the fact that `File.stat` can return `.sym_link` if the `File.handle` itself pertains to a symlink, which is something you have to pretty intentionally do and isn't possible on all systems. The relevant test is here: https://codeberg.org/ziglang/zig/src/commit/2f2b09757682d4c3624d8e6d470852b1d1d6264d/lib/std/fs/test.zig#L244-L249

thanood commented

2025-12-14 11:03:13 +01:00

Author

Well, I wrote that and only then did a deeper dive into zig's fs tests.

are you seeing that behavior locally?

No, I don't. Sorry if that caused some confusion.

I guess I'm seeing how to do that in the above comment which I edited before I saw your answer. 😃

Well, I wrote that and only then did a deeper dive into zig's fs tests. > are you seeing that behavior locally? No, I don't. Sorry if that caused some confusion. I guess I'm seeing how to do that in the above comment which I edited before I saw your answer. 😃

👍 1

squeek502 commented

2025-12-28 11:02:13 +01:00

Member

Fixed by #30186 and #30232

Fixed by https://codeberg.org/ziglang/zig/pulls/30186 and https://codeberg.org/ziglang/zig/pulls/30232

❤️ 1

squeek502 closed this issue

2025-12-28 11:02:16 +01:00

alexrp added this to the 0.16.0 milestone

2026-01-07 01:28:24 +01:00