Skip to content

Update documentation for wasi:filesystem:descriptor#link-at. #848

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wingo wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Update documentation for wasi:filesystem:descriptor#link-at. #848

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e5a9d18
Update documentation for `wasi:filesystem:descriptor#link-at`.
wingo Dec 9, 2025
cc52ae2
Add language forbidding hard links to directories.
wingo Dec 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions proposals/filesystem/wit-0.3.0-draft/types.wit
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -489,11 +489,11 @@ interface types {

/// Create a hard link.
///
/// Fails with `error-code::no-entry` if the old path does not exist,
/// with `error-code::exist` if the new path already exists, and
/// `error-code::not-permitted` if the old path is not a file.
/// Behavior is as described by [POSIX
Copy link
Contributor

@vados-cosmonic vados-cosmonic Feb 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would you mind keeping the previous description of failure modes, and adding this prose + link at the bottom with something like "for more information, see " ?

Laying out the common failure mode and meanings is reasonable in the docs, rather than (for the same reason we note the failure mode for hard links).

Copy link
Contributor Author

@wingo wingo Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if only mentioning a subset of error modes might confuse the reader as being exhaustive; that was certainly my confusion when I read this at first.

The case of hard links is different, because it refines POSIX.

Copy link
Contributor

@vados-cosmonic vados-cosmonic Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah that's a great point.

It's a bit crude but I really want to optimize for saving the user a dig down the rabbit hole if we know the answer for at least some of the platforms and corner cases. What do you think about a note that it is non-exhaustive?

Copy link
Member

@badeend badeend Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW, the sockets interface describes the possible errors too. But phrases them as "Typical errors"

This communicates clearly what common failure modes the caller can expect, but also doesn't rigidly tie things down for the implementation.

/// `linkat`](https://pubs.opengroup.org/onlinepubs/9699919799/functions/link.html).
///
/// Note: This is similar to `linkat` in POSIX.
/// Hard links between directories are forbidden, and produce either
/// `error-code::access` or `error-code::not-permitted` error results.
@since(version = 0.3.0-rc-2025-09-16)
link-at: async func(
/// Flags determining the method of how the path is resolved.
Expand Down