net: document that a keep-alive failure also returns a timeout

Updates #31449

Change-Id: I76490c5e83eb2f7ba529b387a57ba088428aece5
Reviewed-on: https://go-review.googlesource.com/c/go/+/189757
Run-TryBot: Ian Lance Taylor <iant@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Emmanuel Odeke <emm.odeke@gmail.com>
Reviewed-by: Filippo Valsorda <filippo@golang.org>

diff --git a/src/net/net.go b/src/net/net.go
index 4ed40237a8a9e0749a57aa9c00cff7b126872d8a..38c6b9963747a5bb81293252d11b70643824a542 100644 (file)
--- a/src/net/net.go
+++ b/src/net/net.go
@@ -146,6 +146,13 @@ type Conn interface {
        // the deadline after successful Read or Write calls.
        //
        // A zero value for t means I/O operations will not time out.
+       //
+       // Note that if a TCP connection has keep-alive turned on,
+       // which is the default unless overridden by Dialer.KeepAlive
+       // or ListenConfig.KeepAlive, then a keep-alive failure may
+       // also return a timeout error. On Unix systems a keep-alive
+       // failure on I/O can be detected using
+       // errors.Is(err, syscall.ETIMEDOUT).
        SetDeadline(t time.Time) error
 
        // SetReadDeadline sets the deadline for future Read calls