Merge remote-tracking branch 'upstream/master' into net-url-testparseerrors-fix

Author: stefanb

doc/go1.13.html

@@ -525,6 +525,37 @@ <h3 id="crypto/ed25519"><a href="/pkg/crypto/ed25519/">crypto/ed25519</a></h3>
   <code>crypto/ed25519</code> when used with Go 1.13+.
 </p>
 
+<h3 id="error_wrapping">Error wrapping</h3>
+
+<p><!-- CL 163558, 176998 -->
+  Go 1.13 contains support for error wrapping, as first proposed in
+  the <a href="https://go.googlesource.com/proposal/+/master/design/29934-error-values.md">
+  Error Values proposal</a> and discussed on <a href="https://golang.org/issue/29934">the
+  associated issue</a>.
+</p>
+<p>
+  An error <code>e</code> can <em>wrap</em> another error <code>w</code> by providing
+  an <code>Unwrap</code> method that returns <code>w</code>. Both <code>e</code>
+  and <code>w</code> are available to programs, allowing <code>e</code> to provide
+  additional context to <code>w</code> or to reinterpret it while still allowing
+  programs to make decisions based on <code>w</code>.
+</p>
+<p>
+  To support wrapping, <a href="#fmt"><code>fmt.Errorf</code></a> now has a <code>%w</code>
+  verb for creating wrapped errors, and three new functions in
+  the <a href="#errors"><code>errors</code></a> package (
+  <a href="/pkg/errors#Unwrap"><code>errors.Unwrap</code></a>,
+  <a href="/pkg/errors#Is"><code>errors.Is</code></a> and
+  <a href="/pkg/errors#As"><code>errors.As</code></a>) simplify unwrapping
+  and inspecting wrapped errors.
+</p>
+<p>
+  For more information, read the <a href="/pkg/errors/"><code>errors</code> package
+  documentation</a>, or see
+  the <a href="https://golang.org/wiki/ErrorValueFAQ">Error Value FAQ</a>.
+  There will soon be a blog post as well.
+</p>
+
 <h3 id="minor_library_changes">Minor changes to the library</h3>
 
 <p>
@@ -612,7 +643,8 @@ <h3 id="minor_library_changes">Minor changes to the library</h3>
   <dd>
     <!-- CL 163558 -->
     <p>
-      The new function <a href="/pkg/errors/#As"><code>As</code></a> finds the first error in a given error’s chain
+      The new function <a href="/pkg/errors/#As"><code>As</code></a> finds the first
+      error in a given error’s chain (sequence of wrapped errors)
       that matches a given target’s type, and if so, sets the target to that error value.
     </p>
     <p>

src/cmd/go/internal/version/exe.go

@@ -103,6 +103,11 @@ func (x *elfExe) ReadData(addr, size uint64) ([]byte, error) {
 }
 
 func (x *elfExe) DataStart() uint64 {
+	for _, s := range x.f.Sections {
+		if s.Name == ".go.buildinfo" {
+			return s.Addr
+		}
+	}
 	for _, p := range x.f.Progs {
 		if p.Type == elf.PT_LOAD && p.Flags&(elf.PF_X|elf.PF_W) == elf.PF_W {
 			return p.Vaddr

src/cmd/go/testdata/script/mod_invalid_version.txt

@@ -141,7 +141,7 @@ go mod edit -require golang.org/x/[email protected]
 go mod edit -replace golang.org/x/[email protected]=golang.org/x/[email protected]
 cd outside
 ! go get -d golang.org/x/text@upgrade
-stderr 'go get golang.org/x/text@upgrade: golang.org/x/text@v1.999999.0: invalid version: unknown revision v1.999999.0'
+stderr 'go: [email protected] requires\n\tgolang.org/x/text@v1.999999.0: reading golang.org/x/text/go.mod at revision v1.999999.0: unknown revision v1.999999.0'
 cd ..
 go get -d golang.org/x/text@upgrade
 go list -m golang.org/x/text

src/cmd/go/testdata/script/version.txt

@@ -8,5 +8,12 @@ go version -m fortune.exe
 stdout '^\tpath\trsc.io/fortune'
 stdout '^\tmod\trsc.io/fortune\tv1.0.0'
 
+go build -buildmode=pie -o external.exe rsc.io/fortune
+go version external.exe
+stdout '^external.exe: .+'
+go version -m external.exe
+stdout '^\tpath\trsc.io/fortune'
+stdout '^\tmod\trsc.io/fortune\tv1.0.0'
+
 -- go.mod --
 module m

src/errors/errors.go

@@ -3,9 +3,58 @@
 // license that can be found in the LICENSE file.
 
 // Package errors implements functions to manipulate errors.
+//
+// The New function creates errors whose only content is a text message.
+//
+// The Unwrap, Is and As functions work on errors that may wrap other errors.
+// An error wraps another error if its type has the method
+//
+//	Unwrap() error
+//
+// If e.Unwrap() returns a non-nil error w, then we say that e wraps w.
+//
+// A simple way to create wrapped errors is to call fmt.Errorf and apply the %w verb
+// to the error argument:
+//
+//	fmt.Errorf("... %w ...", ..., err, ...).Unwrap()
+//
+// returns err.
+//
+// Unwrap unpacks wrapped errors. If its argument's type has an
+// Unwrap method, it calls the method once. Otherwise, it returns nil.
+//
+// Is unwraps its first argument sequentially looking for an error that matches the
+// second. It reports whether it finds a match. It should be used in preference to
+// simple equality checks:
+//
+//	if errors.Is(err, os.ErrExist)
+//
+// is preferable to
+//
+//	if err == os.ErrExist
+//
+// because the former will succeed if err wraps os.ErrExist.
+//
+// As unwraps its first argument sequentially looking for an error that can be
+// assigned to its second argument, which must be a pointer. If it succeeds, it
+// performs the assignment and returns true. Otherwise, it returns false. The form
+//
+//	var perr *os.PathError
+//	if errors.As(err, &perr) {
+//		fmt.Println(perr.Path)
+//	}
+//
+// is preferable to
+//
+//	if perr, ok := err.(*os.PathError); ok {
+//		fmt.Println(perr.Path)
+//	}
+//
+// because the former will succeed if err wraps an *os.PathError.
 package errors
 
 // New returns an error that formats as the given text.
+// Each call to New returns a distinct error value even if the text is identical.
 func New(text string) error {
 	return &errorString{text}
 }

src/errors/wrap.go

@@ -23,6 +23,9 @@ func Unwrap(err error) error {
 
 // Is reports whether any error in err's chain matches target.
 //
+// The chain consists of err itself followed by the sequence of errors obtained by
+// repeatedly calling Unwrap.
+//
 // An error is considered to match a target if it is equal to that target or if
 // it implements a method Is(error) bool such that Is(target) returns true.
 func Is(err, target error) bool {
@@ -50,6 +53,9 @@ func Is(err, target error) bool {
 // As finds the first error in err's chain that matches target, and if so, sets
 // target to that error value and returns true.
 //
+// The chain consists of err itself followed by the sequence of errors obtained by
+// repeatedly calling Unwrap.
+//
 // An error matches target if the error's concrete value is assignable to the value
 // pointed to by target, or if the error has a method As(interface{}) bool such that
 // As(target) returns true. In the latter case, the As method is responsible for

src/syscall/syscall_freebsd.go

@@ -19,12 +19,12 @@ import (
 
 const (
 	_SYS_FSTAT_FREEBSD12         = 551 // { int fstat(int fd, _Out_ struct stat *sb); }
-	_SYS_FSTATAT_FREEBSD12       = 552 // { int fstatat(int fd, _In_z_ char *path, \
-	_SYS_GETDIRENTRIES_FREEBSD12 = 554 // { ssize_t getdirentries(int fd, \
-	_SYS_STATFS_FREEBSD12        = 555 // { int statfs(_In_z_ char *path, \
-	_SYS_FSTATFS_FREEBSD12       = 556 // { int fstatfs(int fd, \
-	_SYS_GETFSSTAT_FREEBSD12     = 557 // { int getfsstat( \
-	_SYS_MKNODAT_FREEBSD12       = 559 // { int mknodat(int fd, _In_z_ char *path, \
+	_SYS_FSTATAT_FREEBSD12       = 552 // { int fstatat(int fd, _In_z_ char *path, _Out_ struct stat *buf, int flag); }
+	_SYS_GETDIRENTRIES_FREEBSD12 = 554 // { ssize_t getdirentries(int fd, _Out_writes_bytes_(count) char *buf, size_t count, _Out_ off_t *basep); }
+	_SYS_STATFS_FREEBSD12        = 555 // { int statfs(_In_z_ char *path, _Out_ struct statfs *buf); }
+	_SYS_FSTATFS_FREEBSD12       = 556 // { int fstatfs(int fd, _Out_ struct statfs *buf); }
+	_SYS_GETFSSTAT_FREEBSD12     = 557 // { int getfsstat(_Out_writes_bytes_opt_(bufsize) struct statfs *buf, long bufsize, int mode); }
+	_SYS_MKNODAT_FREEBSD12       = 559 // { int mknodat(int fd, _In_z_ char *path, mode_t mode, dev_t dev); }
 )
 
 // See https://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/versions.html.