Skip to content
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.

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

os: Readlink docs should mention behavior for relative paths #57766

Open
bcmills opened this issue Jan 12, 2023 · 2 comments
Open

os: Readlink docs should mention behavior for relative paths #57766

bcmills opened this issue Jan 12, 2023 · 2 comments
Assignees
Labels
Documentation NeedsFix The path to resolution is known, but the work has not been done.
Milestone

Comments

@bcmills
Copy link
Member

bcmills commented Jan 12, 2023

The documentation for os.Readlink currently says:

Readlink returns the destination of the named symbolic link. If there is an error, it will be of type *PathError.

While that is true, it also omits an important piece of information about “the destination”: if the symlink target is relative, Readlink will return that raw relative string directly. It will not do any additional work to make the path either absolute or relative to the current working directory. A reader who is not thinking very deeply about relative paths may well treat the result as a path, not a special symlink path blob.¹

That is consistent with the Unix readlink system call, but then again, the Go os package is different from the Unix syscall package for a reason. We should probably call this out more explicitly in the documentation, and perhaps provide an example of how to use Readlink to correctly resolve a symlink to a filesystem path.


¹ Per https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13,
“[T]he system shall prefix the remaining pathname, if any, with the contents of the symbolic link …. If the resulting pathname does not begin with a , the predecessor of the first filename of the pathname is taken to be the directory containing the symbolic link.”

@bcmills bcmills added the NeedsFix The path to resolution is known, but the work has not been done. label Jan 12, 2023
@bcmills bcmills added this to the Go1.21 milestone Jan 12, 2023
@bcmills bcmills self-assigned this Jan 12, 2023
@bcmills
Copy link
Member Author

bcmills commented Jan 12, 2023

(Found via #57754.)

@bcmills
Copy link
Member Author

bcmills commented Jan 12, 2023

Similarly, the documentation for Lstat should probably mention that its behavior (like the Unix lstat system call) depends on whether name ends in a trailing slash. (If it does, the symlink is followed.)

https://go.dev/play/p/ZxOq1dwAUfh

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Development

No branches or pull requests

2 participants