os: document and emphasize a potential misuse of File.Fd

This CL revises the document of File.Fd that explicitly points
its user to runtime.SetFinalizer where contains the information
that a file descriptor could be closed in a finalizer and therefore
causes a failure in syscall.Write if runtime.KeepAlive is not invoked.

The CL also suggests an alternative of File.Fd towards File.SyscallConn.

Fixes #41505

Change-Id: I6816f0157add48b649bf1fb793cf19dcea6894b5
Reviewed-on: https://go-review.googlesource.com/c/go/+/256899
Reviewed-by: Rob Pike <r@golang.org>
Trust: Ian Lance Taylor <iant@golang.org>

3 files changed, 19 insertions, 6 deletions

diff --git a/src/os/file_plan9.go b/src/os/file_plan9.go
index 043500744b..5e0ad68208 100644
--- a/src/os/file_plan9.go
+++ b/src/os/file_plan9.go
@@ -29,8 +29,13 @@ type file struct {
 }
 
 // Fd returns the integer Plan 9 file descriptor referencing the open file.
-// The file descriptor is valid only until f.Close is called or f is garbage collected.
-// On Unix systems this will cause the SetDeadline methods to stop working.
+// If f is closed, the file descriptor becomes invalid.
+// If f is garbage collected, a finalizer may close the file descriptor,
+// making it invalid; see runtime.SetFinalizer for more information on when
+// a finalizer might be run. On Unix systems this will cause the SetDeadline
+// methods to stop working.
+//
+// As an alternative, see the f.SyscallCon method.
 func (f *File) Fd() uintptr {
 	if f == nil {
 		return ^(uintptr(0))
diff --git a/src/os/file_unix.go b/src/os/file_unix.go
index dc7d868a32..c4dd4fc6a9 100644
--- a/src/os/file_unix.go
+++ b/src/os/file_unix.go
@@ -62,8 +62,13 @@ type file struct {
 }
 
 // Fd returns the integer Unix file descriptor referencing the open file.
-// The file descriptor is valid only until f.Close is called or f is garbage collected.
-// On Unix systems this will cause the SetDeadline methods to stop working.
+// If f is closed, the file descriptor becomes invalid.
+// If f is garbage collected, a finalizer may close the file descriptor,
+// making it invalid; see runtime.SetFinalizer for more information on when
+// a finalizer might be run. On Unix systems this will cause the SetDeadline
+// methods to stop working.
+//
+// As an alternative, see the f.SyscallCon method.
 func (f *File) Fd() uintptr {
 	if f == nil {
 		return ^(uintptr(0))
diff --git a/src/os/file_windows.go b/src/os/file_windows.go
index cc695fd94c..f744a35023 100644
--- a/src/os/file_windows.go
+++ b/src/os/file_windows.go
@@ -26,8 +26,11 @@ type file struct {
 }
 
 // Fd returns the Windows handle referencing the open file.
-// The handle is valid only until f.Close is called or f is garbage collected.
-// On Unix systems this will cause the SetDeadline methods to stop working.
+// If f is closed, the file descriptor becomes invalid.
+// If f is garbage collected, a finalizer may close the file descriptor,
+// making it invalid; see runtime.SetFinalizer for more information on when
+// a finalizer might be run. On Unix systems this will cause the SetDeadline
+// methods to stop working.
 func (file *File) Fd() uintptr {
 	if file == nil {
 		return uintptr(syscall.InvalidHandle)