os: document that Windows Symlink to missing target creates file symlink

Fixes #39183

Change-Id: Iec4a5a561182ade57dc7dc24247710005d6b9f21
Reviewed-on: https://go-review.googlesource.com/c/go/+/314275
Trust: Ian Lance Taylor <iant@golang.org>
Reviewed-by: Emmanuel Odeke <emmanuel@orijtech.com>
Run-TryBot: Emmanuel Odeke <emmanuel@orijtech.com>
TryBot-Result: Go Bot <gobot@golang.org>

diff --git a/src/os/file_plan9.go b/src/os/file_plan9.go
index 4f384e9211061d526dd6c3ca736572e79389235d..604aea607bcf304e4ac111fbdd4aeb4e3c596cc0 100644 (file)
--- a/src/os/file_plan9.go
+++ b/src/os/file_plan9.go
@@ -440,6 +440,8 @@ func Link(oldname, newname string) error {
 }
 
 // Symlink creates newname as a symbolic link to oldname.
+// On Windows, a symlink to a non-existent oldname creates a file symlink;
+// if oldname is later created as a directory the symlink will not work.
 // If there is an error, it will be of type *LinkError.
 func Symlink(oldname, newname string) error {
        return &LinkError{"symlink", oldname, newname, syscall.EPLAN9}

diff --git a/src/os/file_unix.go b/src/os/file_unix.go
index deec41324b2844b1397f8df3a518a4014c38a787..a2531b9656278cac8e3bd4155b83e4813415bf1a 100644 (file)
--- a/src/os/file_unix.go
+++ b/src/os/file_unix.go
@@ -351,6 +351,8 @@ func Link(oldname, newname string) error {
 }
 
 // Symlink creates newname as a symbolic link to oldname.
+// On Windows, a symlink to a non-existent oldname creates a file symlink;
+// if oldname is later created as a directory the symlink will not work.
 // If there is an error, it will be of type *LinkError.
 func Symlink(oldname, newname string) error {
        e := ignoringEINTR(func() error {

diff --git a/src/os/file_windows.go b/src/os/file_windows.go
index a2cb96e45737f7320b0615ca5894f1059d8aa43e..378e2b1c7d69c71b464eb59b6104fdce76467248 100644 (file)
--- a/src/os/file_windows.go
+++ b/src/os/file_windows.go
@@ -327,6 +327,8 @@ func Link(oldname, newname string) error {
 }
 
 // Symlink creates newname as a symbolic link to oldname.
+// On Windows, a symlink to a non-existent oldname creates a file symlink;
+// if oldname is later created as a directory the symlink will not work.
 // If there is an error, it will be of type *LinkError.
 func Symlink(oldname, newname string) error {
        // '/' does not work in link's content