path,path/filepath: add Join examples with ".." components

People sometimes expect Join to trim .. components from its arguments
before joining, and are surprised that it doesn't. This is bad if they
were relying on that assumed behaviour to prevent directory traversal
attacks.

While a careful reading of the documentation for Join and Clean
might dispel this notion, it is not obvious at first glance.

Add a case to the examples to nudge people in the right direction.

Updates #40373

Change-Id: Ib5792c12ba1000811a0c0eb77048196d0b26da60
Reviewed-on: https://go-review.googlesource.com/c/go/+/249177
Run-TryBot: Ian Lance Taylor <iant@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>
Reviewed-by: Rob Pike <r@golang.org>

diff --git a/src/path/example_test.go b/src/path/example_test.go
index 67b9718664083b2b0ed51946f12759fb3a01e49a..e30ebd13dcd739c32657e8a8b482d1d6503822e1 100644 (file)
--- a/src/path/example_test.go
+++ b/src/path/example_test.go
@@ -79,13 +79,18 @@ func ExampleJoin() {
        fmt.Println(path.Join("a", "b", "c"))
        fmt.Println(path.Join("a", "b/c"))
        fmt.Println(path.Join("a/b", "c"))
+
+       fmt.Println(path.Join("a/b", "../../../xyz"))
+
        fmt.Println(path.Join("", ""))
        fmt.Println(path.Join("a", ""))
        fmt.Println(path.Join("", "a"))
+
        // Output:
        // a/b/c
        // a/b/c
        // a/b/c
+       // ../xyz
        //
        // a
        // a

diff --git a/src/path/filepath/example_unix_test.go b/src/path/filepath/example_unix_test.go
index 23f21380d01cb2fcf60e849f7fc425666541c87d..c9d694451889b8aee80e9029bf082fee2da3d3dd 100644 (file)
--- a/src/path/filepath/example_unix_test.go
+++ b/src/path/filepath/example_unix_test.go
@@ -72,12 +72,16 @@ func ExampleJoin() {
        fmt.Println(filepath.Join("a", "b/c"))
        fmt.Println(filepath.Join("a/b", "c"))
        fmt.Println(filepath.Join("a/b", "/c"))
+
+       fmt.Println(filepath.Join("a/b", "../../../xyz"))
+
        // Output:
        // On Unix:
        // a/b/c
        // a/b/c
        // a/b/c
        // a/b/c
+       // ../xyz
 }
 
 func ExampleMatch() {