archive/tar, archive/zip: document ErrInsecurePath and GODEBUG setting

These are mentioned in the release notes but not the actual doc comments.
Nothing should exist only in release notes.

Change-Id: I8d10f25a2c9b2677231929ba3f393af9034b777b
Reviewed-on: https://go-review.googlesource.com/c/go/+/462195
Run-TryBot: Russ Cox <rsc@golang.org>
Reviewed-by: Damien Neil <dneil@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>

2 files changed, 15 insertions, 1 deletions

diff --git a/src/archive/tar/reader.go b/src/archive/tar/reader.go
index 82a5a5a293..768ca1968d 100644
--- a/src/archive/tar/reader.go
+++ b/src/archive/tar/reader.go
@@ -43,8 +43,14 @@ func NewReader(r io.Reader) *Reader {
 // Next advances to the next entry in the tar archive.
 // The Header.Size determines how many bytes can be read for the next file.
 // Any remaining data in the current file is automatically discarded.
+// At the end of the archive, Next returns the error io.EOF.
 //
-// io.EOF is returned at the end of the input.
+// If Next encounters a non-local name (as defined by [filepath.IsLocal])
+// and the GODEBUG environment variable contains `tarinsecurepath=0`,
+// Next returns the header with an ErrInsecurePath error.
+// A future version of Go may introduce this behavior by default.
+// Programs that want to accept non-local names can ignore
+// the ErrInsecurePath error and use the returned header.
 func (tr *Reader) Next() (*Header, error) {
 	if tr.err != nil {
 		return nil, tr.err
diff --git a/src/archive/zip/reader.go b/src/archive/zip/reader.go
index a2ae74e541..a1554d2c52 100644
--- a/src/archive/zip/reader.go
+++ b/src/archive/zip/reader.go
@@ -87,6 +87,14 @@ func OpenReader(name string) (*ReadCloser, error) {
 
 // NewReader returns a new Reader reading from r, which is assumed to
 // have the given size in bytes.
+//
+// If any file inside the archive uses a non-local name
+// (as defined by [filepath.IsLocal]) or a name containing backslashes
+// and the GODEBUG environment variable contains `zipinsecurepath=0`,
+// NewReader returns the reader with an ErrInsecurePath error.
+// A future version of Go may introduce this behavior by default.
+// Programs that want to accept non-local names can ignore
+// the ErrInsecurePath error and use the returned reader.
 func NewReader(r io.ReaderAt, size int64) (*Reader, error) {
 	if size < 0 {
 		return nil, errors.New("zip: size cannot be negative")