os: Readlink docs should mention behavior for relative paths #57766
Description
The documentation for os.Readlink currently says:
Readlinkreturns 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.”