os: Root documentation does not mention relative paths

[AlekSi]

Go version

go version go1.26.2 darwin/arm64

Output of go env in your module/workspace:

Not relevant.

What did you do?

1. Read https://pkg.go.dev/os#Root documentation.
2. Run https://go.dev/play/p/q9mW-k5sg-X
3. Got confused.

What did you see happen?

2009/11/10 23:00:00 root    /tmp/860037159
2009/11/10 23:00:00 mkdirat /tmp/860037159/123: path escapes from parent

What did you expect to see?

Root documentation says (relevant bits):

Root may be used to only access files within a single directory tree.

Methods on Root can only access files and directories beneath a root directory. If any component of a file name passed to a method of Root references a location outside the root, the method returns an error. File names may reference the directory itself (.).

Methods on Root will follow symbolic links, but symbolic links may not reference a location outside the root. Symbolic links must not be absolute.

/tmp/860037159 and /tmp/860037159/123 are within a single directory tree. /tmp/860037159/123 is beneath a root directory /tmp/860037159. There are no symbolic links. So what I do is correct according to the documentation.

I guess what documentation fails to mention is that the arguments to root methods must be relative paths, even if there are no symbolic links. If the current behavior is intentional, it should be documented; "within a single directory tree" and " beneath a root directory" are not enough.

[Jah-yee]

Thanks for the detailed issue! I've analyzed the behavior and here's what I found:

Root cause: The documentation does mention that methods "only access files and directories beneath a root directory" but doesn't explicitly state that path arguments must be relative paths.

The fix needed: Update the os.Root documentation to clarify that path arguments to Root methods must be relative paths, not absolute paths. This is consistent with the security design where relative paths prevent dotdot attacks.

Example clarification that could be added to the docs:

Path arguments passed to Root methods must be relative paths (not absolute paths). Absolute paths, even when they reference locations within the root, will return an error.

Files that would need updating:

• src/os/os.go (the Root type documentation) - specifically the method docs for , , , etc.

Would be happy to submit a PR with this documentation fix once the issue is confirmed. The fix is straightforward - just adding a line to the relevant method docs.

[neild]

Perhaps the documentation can be clearer, but it does state:

If any component of a file name passed to a method of Root references a location outside the root

If the root is "/tmp/860037159" and the file name is "/tmp/860037159/123", then the component "/tmp" references a location outside the root.

[mwriter]

If the root is "/tmp/860037159" and the file name is "/tmp/860037159/123", then the component "/tmp" references a location outside the root.

No, it's about something else, I misunderstood it myself at first.

I guess what documentation fails to mention is that the arguments to root methods must be relative paths

He is absolutely right, the doc doesn't emphasize this.
As an example of proper documentation:
https://pkg.go.dev/os#Root.Link
https://pkg.go.dev/os#Root.Rename

Both paths are relative to the root.

[AlekSi]

If the root is "/tmp/860037159" and the file name is "/tmp/860037159/123", then the component "/tmp" references a location outside the root.

It is the same if both root and file (directory) name are just "/tmp": https://go.dev/play/p/k2eBObO7Kxn

[mwriter]

It is the same if both root and file (directory) name are just "/tmp": https://go.dev/play/p/k2eBObO7Kxn

But you do realize that this code is working correctly, right?
As I understand it, your issue is specifically about documentation.

[AlekSi]

Well, I'm not sure how it should work (it could be argued either way), but I do think it is probably too late to change the behavior, and there is also no strong reason to do so, so yes, what I want is a documentation tweak. The error message could also be improved, I think, especially in the second example.