os: Readlink docs should mention behavior for relative paths

[bcmills]

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 <slash>, the predecessor of the first filename of the pathname is taken to be the directory containing the symbolic link.”

[bcmills]

(Found via #57754.)

[bcmills]

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

[gopherbot]

Change https://go.dev/cl/546995 mentions this issue: os: document Readlink behavior for relative links