Repository: rust
Issue: [discussion] `ErrorKind::FilesystemLoop` from `io_error_more`
Labels: T-libs-api,C-discussion

@rustbot label C-discussion

Main tracking issue: #86442

## Background

The [`io_error_more` feature](https://github.com/rust-lang/rust/issues/86442) introduced 21 new variants into [`ErrorKind`](https://doc.rust-lang.org/nightly/std/io/enum.ErrorKind.html). They were [FCP'd back in December 2022](https://github.com/rust-lang/rust/issues/86442#issuecomment-1368082102), 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

<details>

<summary>Old description</summary>

> 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.

</details>

## 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_