os: clarify behavior of TempDir

Fixes #19695

Change-Id: Ie5103f7905969e25dba6e5fb37344b70e807fc69
Reviewed-on: https://go-review.googlesource.com/45702
Run-TryBot: Brad Fitzpatrick <bradfitz@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>

src/os/file.go

@@ -279,3 +279,16 @@ func (f *File) wrapErr(op string, err error) error {
 	}
 	return &PathError{op, f.name, err}
 }
+
+// TempDir returns the default directory to use for temporary files.
+//
+// On Unix systems, it returns $TMPDIR if non-empty, else /tmp.
+// On Windows, it uses GetTempPath, returning the first non-empty
+// value from %TMP%, %TEMP%, %USERPROFILE%, or the Windows directory.
+// On Plan 9, it returns /tmp.
+//
+// The directory is neither guaranteed to exist nor have accessible
+// permissions.
+func TempDir() string {
+	return tempDir()
+}

src/os/file_plan9.go

@@ -478,8 +478,7 @@ func (f *File) Chown(uid, gid int) error {
 	return &PathError{"chown", f.name, syscall.EPLAN9}
 }
 
-// TempDir returns the default directory to use for temporary files.
-func TempDir() string {
+func tempDir() string {
 	return "/tmp"
 }
 

src/os/file_unix.go

@@ -294,8 +294,7 @@ func Remove(name string) error {
 	return &PathError{"remove", name, e}
 }
 
-// TempDir returns the default directory to use for temporary files.
-func TempDir() string {
+func tempDir() string {
 	dir := Getenv("TMPDIR")
 	if dir == "" {
 		if runtime.GOOS == "android" {

src/os/file_windows.go

@@ -325,8 +325,7 @@ func Pipe() (r *File, w *File, err error) {
 	return newFile(p[0], "|0", "file"), newFile(p[1], "|1", "file"), nil
 }
 
-// TempDir returns the default directory to use for temporary files.
-func TempDir() string {
+func tempDir() string {
 	n := uint32(syscall.MAX_PATH)
 	for {
 		b := make([]uint16, n)