os: add ReadFile, WriteFile, CreateTemp (was TempFile), MkdirTemp (was TempDir) from io/ioutil

io/ioutil was a poorly defined collection of helpers.
Proposal #40025 moved out the generic I/O helpers to io.
This CL for proposal #42026 moves the OS-specific helpers to os,
making the entire io/ioutil package deprecated.

For #42026.

Change-Id: I018bcb2115ef2ff1bc7ca36a9247eda429af21ad
Reviewed-on: https://go-review.googlesource.com/c/go/+/266364
Trust: Russ Cox <[email protected]>
Trust: Emmanuel Odeke <[email protected]>
Run-TryBot: Russ Cox <[email protected]>
TryBot-Result: Go Bot <[email protected]>
Reviewed-by: Emmanuel Odeke <[email protected]>

Author: rsc

src/io/ioutil/ioutil.go

@@ -3,6 +3,11 @@
 // license that can be found in the LICENSE file.
 
 // Package ioutil implements some I/O utility functions.
+//
+// As of Go 1.16, the same functionality is now provided
+// by package io or package os, and those implementations
+// should be preferred in new code.
+// See the specific function documentation for details.
 package ioutil
 
 import (
@@ -26,67 +31,30 @@ func ReadAll(r io.Reader) ([]byte, error) {
 // A successful call returns err == nil, not err == EOF. Because ReadFile
 // reads the whole file, it does not treat an EOF from Read as an error
 // to be reported.
+//
+// As of Go 1.16, this function simply calls os.ReadFile.
 func ReadFile(filename string) ([]byte, error) {
-	f, err := os.Open(filename)
-	if err != nil {
-		return nil, err
-	}
-	defer f.Close()
-	// It's a good but not certain bet that FileInfo will tell us exactly how much to
-	// read, so let's try it but be prepared for the answer to be wrong.
-	const minRead = 512
-	var n int64 = minRead
-
-	if fi, err := f.Stat(); err == nil {
-		// As initial capacity for readAll, use Size + a little extra in case Size
-		// is zero, and to avoid another allocation after Read has filled the
-		// buffer. The readAll call will read into its allocated internal buffer
-		// cheaply. If the size was wrong, we'll either waste some space off the end
-		// or reallocate as needed, but in the overwhelmingly common case we'll get
-		// it just right.
-		if size := fi.Size() + minRead; size > n {
-			n = size
-		}
-	}
-
-	if int64(int(n)) != n {
-		n = minRead
-	}
-
-	b := make([]byte, 0, n)
-	for {
-		if len(b) == cap(b) {
-			// Add more capacity (let append pick how much).
-			b = append(b, 0)[:len(b)]
-		}
-		n, err := f.Read(b[len(b):cap(b)])
-		b = b[:len(b)+n]
-		if err != nil {
-			if err == io.EOF {
-				err = nil
-			}
-			return b, err
-		}
-	}
+	return os.ReadFile(filename)
 }
 
 // WriteFile writes data to a file named by filename.
 // If the file does not exist, WriteFile creates it with permissions perm
 // (before umask); otherwise WriteFile truncates it before writing, without changing permissions.
+//
+// As of Go 1.16, this function simply calls os.WriteFile.
 func WriteFile(filename string, data []byte, perm fs.FileMode) error {
-	f, err := os.OpenFile(filename, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, perm)
-	if err != nil {
-		return err
-	}
-	_, err = f.Write(data)
-	if err1 := f.Close(); err == nil {
-		err = err1
-	}
-	return err
+	return os.WriteFile(filename, data, perm)
 }
 
 // ReadDir reads the directory named by dirname and returns
-// a list of directory entries sorted by filename.
+// a list of fs.FileInfo for the directory's contents,
+// sorted by filename. If an error occurs reading the directory,
+// ReadDir returns no directory entries along with the error.
+//
+// As of Go 1.16, os.ReadDir is a more efficient and correct choice:
+// it returns a list of fs.DirEntry instead of fs.FileInfo,
+// and it returns partial results in the case of an error
+// midway through reading a directory.
 func ReadDir(dirname string) ([]fs.FileInfo, error) {
 	f, err := os.Open(dirname)
 	if err != nil {

src/os/dir.go

@@ -4,7 +4,10 @@
 
 package os
 
-import "io/fs"
+import (
+	"io/fs"
+	"sort"
+)
 
 type readdirMode int
 
@@ -103,3 +106,20 @@ func (f *File) ReadDir(n int) ([]DirEntry, error) {
 // testingForceReadDirLstat forces ReadDir to call Lstat, for testing that code path.
 // This can be difficult to provoke on some Unix systems otherwise.
 var testingForceReadDirLstat bool
+
+// ReadDir reads the named directory,
+// returning all its directory entries sorted by filename.
+// If an error occurs reading the directory,
+// ReadDir returns the entries it was able to read before the error,
+// along with the error.
+func ReadDir(name string) ([]DirEntry, error) {
+	f, err := Open(name)
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+
+	dirs, err := f.ReadDir(-1)
+	sort.Slice(dirs, func(i, j int) bool { return dirs[i].Name() < dirs[j].Name() })
+	return dirs, err
+}

src/os/example_test.go

@@ -9,6 +9,7 @@ import (
 	"io/fs"
 	"log"
 	"os"
+	"path/filepath"
 	"time"
 )
 
@@ -144,3 +145,98 @@ func ExampleUnsetenv() {
 	os.Setenv("TMPDIR", "/my/tmp")
 	defer os.Unsetenv("TMPDIR")
 }
+
+func ExampleReadDir() {
+	files, err := os.ReadDir(".")
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	for _, file := range files {
+		fmt.Println(file.Name())
+	}
+}
+
+func ExampleMkdirTemp() {
+	dir, err := os.MkdirTemp("", "example")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer os.RemoveAll(dir) // clean up
+
+	file := filepath.Join(dir, "tmpfile")
+	if err := os.WriteFile(file, []byte("content"), 0666); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func ExampleMkdirTemp_suffix() {
+	logsDir, err := os.MkdirTemp("", "*-logs")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer os.RemoveAll(logsDir) // clean up
+
+	// Logs can be cleaned out earlier if needed by searching
+	// for all directories whose suffix ends in *-logs.
+	globPattern := filepath.Join(os.TempDir(), "*-logs")
+	matches, err := filepath.Glob(globPattern)
+	if err != nil {
+		log.Fatalf("Failed to match %q: %v", globPattern, err)
+	}
+
+	for _, match := range matches {
+		if err := os.RemoveAll(match); err != nil {
+			log.Printf("Failed to remove %q: %v", match, err)
+		}
+	}
+}
+
+func ExampleCreateTemp() {
+	f, err := os.CreateTemp("", "example")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer os.Remove(f.Name()) // clean up
+
+	if _, err := f.Write([]byte("content")); err != nil {
+		log.Fatal(err)
+	}
+	if err := f.Close(); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func ExampleCreateTemp_suffix() {
+	f, err := os.CreateTemp("", "example.*.txt")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer os.Remove(f.Name()) // clean up
+
+	if _, err := f.Write([]byte("content")); err != nil {
+		f.Close()
+		log.Fatal(err)
+	}
+	if err := f.Close(); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func ExampleReadFile() {
+	data, err := os.ReadFile("testdata/hello")
+	if err != nil {
+		log.Fatal(err)
+	}
+	os.Stdout.Write(data)
+
+	// Output:
+	// Hello, Gophers!
+}
+
+func ExampleWriteFile() {
+	err := os.WriteFile("testdata/hello", []byte("Hello, Gophers!"), 0666)
+	if err != nil {
+		log.Fatal(err)
+	}
+}

src/os/export_test.go

@@ -10,3 +10,4 @@ var Atime = atime
 var LstatP = &lstat
 var ErrWriteAtInAppendMode = errWriteAtInAppendMode
 var TestingForceReadDirLstat = &testingForceReadDirLstat
+var ErrPatternHasSeparator = errPatternHasSeparator

src/os/file.go

@@ -625,3 +625,63 @@ func (dir dirFS) Open(name string) (fs.File, error) {
 	}
 	return f, nil
 }
+
+// ReadFile reads the named file and returns the contents.
+// A successful call returns err == nil, not err == EOF.
+// Because ReadFile reads the whole file, it does not treat an EOF from Read
+// as an error to be reported.
+func ReadFile(name string) ([]byte, error) {
+	f, err := Open(name)
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+
+	var size int
+	if info, err := f.Stat(); err == nil {
+		size64 := info.Size()
+		if int64(int(size64)) == size64 {
+			size = int(size64)
+		}
+	}
+	size++ // one byte for final read at EOF
+
+	// If a file claims a small size, read at least 512 bytes.
+	// In particular, files in Linux's /proc claim size 0 but
+	// then do not work right if read in small pieces,
+	// so an initial read of 1 byte would not work correctly.
+	if size < 512 {
+		size = 512
+	}
+
+	data := make([]byte, 0, size)
+	for {
+		if len(data) >= cap(data) {
+			d := append(data[:cap(data)], 0)
+			data = d[:len(data)]
+		}
+		n, err := f.Read(data[len(data):cap(data)])
+		data = data[:len(data)+n]
+		if err != nil {
+			if err == io.EOF {
+				err = nil
+			}
+			return data, err
+		}
+	}
+}
+
+// WriteFile writes data to the named file, creating it if necessary.
+// If the file does not exist, WriteFile creates it with permissions perm (before umask);
+// otherwise WriteFile truncates it before writing, without changing permissions.
+func WriteFile(name string, data []byte, perm FileMode) error {
+	f, err := OpenFile(name, O_WRONLY|O_CREATE|O_TRUNC, perm)
+	if err != nil {
+		return err
+	}
+	_, err = f.Write(data)
+	if err1 := f.Close(); err1 != nil && err == nil {
+		err = err1
+	}
+	return err
+}

src/os/os_test.go

@@ -419,19 +419,19 @@ func testReadDir(dir string, contents []string, t *testing.T) {
 	}
 }
 
-func TestReaddirnames(t *testing.T) {
+func TestFileReaddirnames(t *testing.T) {
 	testReaddirnames(".", dot, t)
 	testReaddirnames(sysdir.name, sysdir.files, t)
 	testReaddirnames(t.TempDir(), nil, t)
 }
 
-func TestReaddir(t *testing.T) {
+func TestFileReaddir(t *testing.T) {
 	testReaddir(".", dot, t)
 	testReaddir(sysdir.name, sysdir.files, t)
 	testReaddir(t.TempDir(), nil, t)
 }
 
-func TestReadDir(t *testing.T) {
+func TestFileReadDir(t *testing.T) {
 	testReadDir(".", dot, t)
 	testReadDir(sysdir.name, sysdir.files, t)
 	testReadDir(t.TempDir(), nil, t)
@@ -1235,6 +1235,7 @@ func TestChmod(t *testing.T) {
 }
 
 func checkSize(t *testing.T, f *File, size int64) {
+	t.Helper()
 	dir, err := f.Stat()
 	if err != nil {
 		t.Fatalf("Stat %q (looking for size %d): %s", f.Name(), size, err)
@@ -2690,3 +2691,22 @@ func TestDirFS(t *testing.T) {
 		t.Fatal(err)
 	}
 }
+
+func TestReadFileProc(t *testing.T) {
+	// Linux files in /proc report 0 size,
+	// but then if ReadFile reads just a single byte at offset 0,
+	// the read at offset 1 returns EOF instead of more data.
+	// ReadFile has a minimum read size of 512 to work around this,
+	// but test explicitly that it's working.
+	name := "/proc/sys/fs/pipe-max-size"
+	if _, err := Stat(name); err != nil {
+		t.Skip(err)
+	}
+	data, err := ReadFile(name)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(data) == 0 || data[len(data)-1] != '\n' {
+		t.Fatalf("read %s: not newline-terminated: %q", name, data)
+	}
+}