[discussion] `ErrorKind::FilesystemLoop` from `io_error_more`

@rustbot label C-discussion

Main tracking issue: #86442

Background

The io_error_more feature introduced 21 new variants into ErrorKind. They were FCP'd back in December 2022, but there appeared to be quite a lot of disagreement about 4 of the added variants, so the stabilization (#106375) got stalled for over twenty months. Thankfully, the 17 uncontroversial variants got stabilized in #128316, so now we just need to iron out a satisfactory design for the remaining 4 variants, and then they can be stabilized too.

In order to not block any of the remaining variants on each other and to not intertwine the discussions, I've created 4 separate issues, which summarize the concerns & suggestions voiced up until this point and can serve as a place for further discussion.

• FilesystemLoop: you are here
• FilesystemQuotaExceeded: #130190
• CrossesDevices: #130191
• InvalidFilename: #130192

FilesystemLoop

Currently corresponds to ELOOP on Unix and nothing ERROR_CANT_RESOLVE_FILENAME on Windows. (https://github.com/rust-lang/rust/issues/86442#issuecomment-1235763183, #130207)

Current docs description:

Loop in the filesystem or IO subsystem; often, too many levels of symbolic links.

There was a loop (or excessively long chain) resolving a filesystem object or file IO object.

On Unix this is usually the result of a symbolic link loop; or, of exceeding the system-specific limit on the depth of symlink traversal.

Make it correspond to ERROR_CANT_RESOLVE_FILENAME on Windows

Done in #130207

Old description

for ELOOP, Windows appears to give winapi::shared::winerror::ERROR_CANT_RESOLVE_FILENAME in similar situations (e.g. symlink loops). Could we add that in, or perhaps generalise FileSystemLoop to the slightly more general case of being unable to resolve?

Originally posted by Robert Collins in https://github.com/rust-lang/rust/issues/86442#issuecomment-1328334824

In https://github.com/rust-lang/rust/issues/86442#issuecomment-1360188402 Ian Jackson voices a concern that this might not be the only place where ERROR_CANT_RESOLVE_FILENAME appears.

Chris Denton in https://github.com/rust-lang/rust/issues/86442#issuecomment-1360288630 and Robert Collins in https://github.com/rust-lang/rust/issues/86442#issuecomment-1367167550 confirm that this is the only place where Windows currently gives ERROR_CANT_RESOLVE_FILENAME and that there is a good correspondence with Unix's ELOOP (when it comes to symlikns, see below for the other usages of ELOOP).

Ian Jackson agrees with them in https://github.com/rust-lang/rust/pull/106375#issuecomment-1369656136, but proposes this should be done separately from stabilization.

There seems to be a consensus regarding this point.

Bikshed the name: be about loops in general, drop "filesystem" from the name

Unix's ELOOP is not just for symlink loops (or too long symlink chains).

ELOOP itself isn't returned solely when loops are detected. Add to that list mount(2) returning ELOOP for move operations where the target is a child of the source - something that has absolutely nothing to do with symlinks, and execve returning ELOOP for exceeding recursion limits during recursive script execution (since Linux 3.8).

• because OS errors are moving targets, we cannot assume Linux / BSD / others will not introduce a 5th or 6th meaning, and its clear to me at least that Linux doesn't treat ELOOP as a filesystem error but a more general error.

I suggest renaming it to LoopError, but document that it means ELOOP on Linux and ERROR_CANT_RESOLVE_FILENAME on Windows, and either describe what we know right now, or provide breadcrumbs for readers to catch up.

Originally posted by Robert Collins in https://github.com/rust-lang/rust/issues/86442#issuecomment-1367167550

I have a mild preference for renaming FilesystemLoop to something that doesn't include Filesystem, for the same reason: OSes do use it for other errors. For instance, Linux also uses it for keyrings, BPF, network routing/filtering, vhost, and network bridges.

Originally posted by Josh Triplett in https://github.com/rust-lang/rust/issues/106375#issuecomment-1371870620

I disagree with renaming FilesystemLoop.

It is true that Unix has a tendency to reuse errno values, so that any particular errno value can often mean a variety of things. Particularly, less-common (even, obscure) APIs and facilities (ab)use errno values. Attempting to represent all these obscure possibilities leads to descriptions and categorisations that are vague and overlapping. We generally haven't done that and I don't think we should start now. (All of this was discussed at length in the earlier conversations in the tracking issue.)

The APIs available in std will produce this error for filesystem operations, not obscure other purposes. I think calling it FilesystemLoop is sensible.

Originally posted by Ian Jackson in https://github.com/rust-lang/rust/pull/106375#issuecomment-1372131054

Bikeshed the name: be about symlink resolution failure in general, stop mentioning loops

some system calls on Linux also use ELOOP to mean "ELOOP A loop exists in symbolic links encountered during resolution of the path argument, or O_NOFOLLOW was specified and the path argument names a symbolic link." so I think interpreting it as "symlink loop or similar symlink resolve error was encountered" might be an accurate description, although (bike-shedding!) I don't know if FilesystemLoop is an accurate name then, and not something like SymlinkResolutionFailed or such...

Originally posted by Alain Emilia Anna Zscheile in https://github.com/rust-lang/rust/issues/86442#issuecomment-1360459049

Start with the main tracking issue #86442 and the ErrorKind documentation described here, then review the linked discussion about FilesystemLoop semantics and naming across Unix and Windows. Done means reaching agreement on the variant's design and documenting or stabilizing it; this issue does not identify a specific file or test to change.