os: clarify that IsExist and friends do not use errors.Is

Fixes #41122

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

diff --git a/src/os/error.go b/src/os/error.go
index 7cd9f22bfb12a78b5557d37fc4eb067a15c69d6c..704a6fb29e3e68b1863efecf6bcf755b054756f0 100644 (file)
--- a/src/os/error.go
+++ b/src/os/error.go
@@ -76,6 +76,9 @@ func NewSyscallError(syscall string, err error) error {
 // IsExist returns a boolean indicating whether the error is known to report
 // that a file or directory already exists. It is satisfied by ErrExist as
 // well as some syscall errors.
+//
+// This function predates errors.Is. It only supports errors returned by
+// the os package. New code should use errors.Is(err, os.ErrExist).
 func IsExist(err error) bool {
        return underlyingErrorIs(err, ErrExist)
 }
@@ -83,6 +86,9 @@ func IsExist(err error) bool {
 // IsNotExist returns a boolean indicating whether the error is known to
 // report that a file or directory does not exist. It is satisfied by
 // ErrNotExist as well as some syscall errors.
+//
+// This function predates errors.Is. It only supports errors returned by
+// the os package. New code should use errors.Is(err, os.ErrNotExist).
 func IsNotExist(err error) bool {
        return underlyingErrorIs(err, ErrNotExist)
 }
@@ -90,12 +96,21 @@ func IsNotExist(err error) bool {
 // IsPermission returns a boolean indicating whether the error is known to
 // report that permission is denied. It is satisfied by ErrPermission as well
 // as some syscall errors.
+//
+// This function predates errors.Is. It only supports errors returned by
+// the os package. New code should use errors.Is(err, os.ErrPermission).
 func IsPermission(err error) bool {
        return underlyingErrorIs(err, ErrPermission)
 }
 
 // IsTimeout returns a boolean indicating whether the error is known
 // to report that a timeout occurred.
+//
+// This function predates errors.Is, and the notion of whether an
+// error indicates a timeout can be ambiguous. For example, the Unix
+// error EWOULDBLOCK sometimes indicates a timeout and sometimes does not.
+// New code should use errors.Is with a value appropriate to the call
+// returning the error, such as os.ErrDeadlineExceeded.
 func IsTimeout(err error) bool {
        terr, ok := underlyingError(err).(timeout)
        return ok && terr.Timeout()