syscall: document relationship among Errno, errors.Is and os.Err*

- Add doc to syscall.Errno (and syscall.ErrorString for plan9).

- Mention under `syscall` in release notes.

Fixes #33436.

Change-Id: I032ffebaa76ed67eb9d748e7645ca73f26144ea0
Reviewed-on: https://go-review.googlesource.com/c/go/+/191337
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/doc/go1.13.html b/doc/go1.13.html
index 6cee0b28e60e27ab47e06b10c379c59c25901dbf..5760669fe5abebf1b3e195bd5139c7715a6a3874 100644 (file)
--- a/doc/go1.13.html
+++ b/doc/go1.13.html
@@ -961,6 +961,13 @@ godoc
       <a href="/pkg/syscall/?GOOS=windows#Chmod"><code>Chmod</code></a> mode on Windows.
     </p>
 
+    <p><!-- CL 191337 -->
+      Values of type <code>Errno</code> can be tested against error values in
+      the <code>os</code> package,
+      like <a href="/pkg/os/#ErrExist"><code>ErrExist</code></a>, using
+      <a href="/pkg/errors/#Is"><code>errors.Is</code></a>.
+    </p>
+
 </dl><!-- syscall -->
 
 <dl id="syscall/js"><dt><a href="/pkg/syscall/js/">syscall/js</a></dt>

diff --git a/src/syscall/syscall_js.go b/src/syscall/syscall_js.go
index 175fe47fcaa0d3c76a545d4cfe61dda68d0bf865..24fbd51189d9bde21af643b7e4cf54dd01af1d69 100644 (file)
--- a/src/syscall/syscall_js.go
+++ b/src/syscall/syscall_js.go
@@ -44,6 +44,12 @@ const PathMax = 256
 //     if errno != 0 {
 //             err = errno
 //     }
+//
+// Errno values can be tested against error values from the the os package
+// using errors.Is. For example:
+//
+//     _, _, err := syscall.Syscall(...)
+//     if errors.Is(err, os.ErrNotExist) ...
 type Errno uintptr
 
 func (e Errno) Error() string {

diff --git a/src/syscall/syscall_nacl.go b/src/syscall/syscall_nacl.go
index e887b1e04ebc1833acbd9080d1f05875d419f6aa..efc986a6f45f4cde4dacc014c7afa09609146d2d 100644 (file)
--- a/src/syscall/syscall_nacl.go
+++ b/src/syscall/syscall_nacl.go
@@ -51,6 +51,12 @@ const PathMax = 256
 //     if errno != 0 {
 //             err = errno
 //     }
+//
+// Errno values can be tested against error values from the the os package
+// using errors.Is. For example:
+//
+//     _, _, err := syscall.Syscall(...)
+//     if errors.Is(err, os.ErrNotExist) ...
 type Errno uintptr
 
 func (e Errno) Error() string {

diff --git a/src/syscall/syscall_plan9.go b/src/syscall/syscall_plan9.go
index c11f03053142f9ae10c8f19994b985bba2857e04..52a9d2aabeca64de0167b51b6010616097267ffa 100644 (file)
--- a/src/syscall/syscall_plan9.go
+++ b/src/syscall/syscall_plan9.go
@@ -20,6 +20,12 @@ const ImplementsGetwd = true
 const bitSize16 = 2
 
 // ErrorString implements Error's String method by returning itself.
+//
+// ErrorString values can be tested against error values from the the os package
+// using errors.Is. For example:
+//
+//     _, _, err := syscall.Syscall(...)
+//     if errors.Is(err, os.ErrNotExist) ...
 type ErrorString string
 
 func (e ErrorString) Error() string { return string(e) }

diff --git a/src/syscall/syscall_unix.go b/src/syscall/syscall_unix.go
index 59c8c34933d7dc7383deac26d1d0149ad9565f93..4a6305e4c5f7f76083b9b3b97ad177a21017c0ec 100644 (file)
--- a/src/syscall/syscall_unix.go
+++ b/src/syscall/syscall_unix.go
@@ -107,6 +107,12 @@ func (m *mmapper) Munmap(data []byte) (err error) {
 //     if errno != 0 {
 //             err = errno
 //     }
+//
+// Errno values can be tested against error values from the the os package
+// using errors.Is. For example:
+//
+//     _, _, err := syscall.Syscall(...)
+//     if errors.Is(err, os.ErrNotExist) ...
 type Errno uintptr
 
 func (e Errno) Error() string {

diff --git a/src/syscall/syscall_windows.go b/src/syscall/syscall_windows.go
index 2e8edc7accdfd042a2ccf2c3111d202658c0998a..cfa9d9c5d0eeff59390e7e6c76994e96453d6454 100644 (file)
--- a/src/syscall/syscall_windows.go
+++ b/src/syscall/syscall_windows.go
@@ -77,6 +77,12 @@ func UTF16PtrFromString(s string) (*uint16, error) {
 }
 
 // Errno is the Windows error number.
+//
+// Errno values can be tested against error values from the the os package
+// using errors.Is. For example:
+//
+//     _, _, err := syscall.Syscall(...)
+//     if errors.Is(err, os.ErrNotExist) ...
 type Errno uintptr
 
 func langid(pri, sub uint16) uint32 { return uint32(sub)<<10 | uint32(pri) }