os: add File.ReadDir method and DirEntry type

ReadDir provides a portable, efficient way to read a directory
and discover the type of directory entries.
This enables a more efficient file system walk, yet to be added.

See #41467 for the proposal review for the API.

Fixes #41467.

Change-Id: I461a526793ae46df48821aa448b04f1705546739
Reviewed-on: https://go-review.googlesource.com/c/go/+/261540
Trust: Russ Cox <rsc@golang.org>
Run-TryBot: Russ Cox <rsc@golang.org>
Reviewed-by: Rob Pike <r@golang.org>

src/os/dir.go

@@ -4,6 +4,14 @@
 
 package os
 
+type readdirMode int
+
+const (
+	readdirName readdirMode = iota
+	readdirDirEntry
+	readdirFileInfo
+)
+
 // Readdir reads the contents of the directory associated with file and
 // returns a slice of up to n FileInfo values, as would be returned
 // by Lstat, in directory order. Subsequent calls on the same file will yield
@@ -19,11 +27,14 @@ package os
 // nil error. If it encounters an error before the end of the
 // directory, Readdir returns the FileInfo read until that point
 // and a non-nil error.
+//
+// Most clients are better served by the more efficient ReadDir method.
 func (f *File) Readdir(n int) ([]FileInfo, error) {
 	if f == nil {
 		return nil, ErrInvalid
 	}
-	return f.readdir(n)
+	_, _, infos, err := f.readdir(n, readdirFileInfo)
+	return infos, err
 }
 
 // Readdirnames reads the contents of the directory associated with file
@@ -45,5 +56,52 @@ func (f *File) Readdirnames(n int) (names []string, err error) {
 	if f == nil {
 		return nil, ErrInvalid
 	}
-	return f.readdirnames(n)
+	names, _, _, err = f.readdir(n, readdirName)
+	return names, err
+}
+
+// A DirEntry is an entry read from a directory
+// (using the ReadDir function or a File's ReadDir method).
+type DirEntry interface {
+	// Name returns the name of the file (or subdirectory) described by the entry.
+	// This name is only the final element of the path, not the entire path.
+	// For example, Name would return "hello.go" not "/home/gopher/hello.go".
+	Name() string
+
+	// IsDir reports whether the entry describes a subdirectory.
+	IsDir() bool
+
+	// Type returns the type bits for the entry.
+	// The type bits are a subset of the usual FileMode bits, those returned by the FileMode.Type method.
+	Type() FileMode
+
+	// Info returns the FileInfo for the file or subdirectory described by the entry.
+	// The returned FileInfo may be from the time of the original directory read
+	// or from the time of the call to Info. If the file has been removed or renamed
+	// since the directory read, Info may return an error satisfying errors.Is(err, ErrNotExist).
+	// If the entry denotes a symbolic link, Info reports the information about the link itself,
+	// not the link's target.
+	Info() (FileInfo, error)
+}
+
+// ReadDir reads the contents of the directory associated with the file f
+// and returns a slice of DirEntry values in directory order.
+// Subsequent calls on the same file will yield later DirEntry records in the directory.
+//
+// If n > 0, ReadDir returns at most n DirEntry records.
+// In this case, if ReadDir returns an empty slice, it will return an error explaining why.
+// At the end of a directory, the error is io.EOF.
+//
+// If n <= 0, ReadDir returns all the DirEntry records remaining in the directory.
+// When it succeeds, it returns a nil error (not io.EOF).
+func (f *File) ReadDir(n int) ([]DirEntry, error) {
+	if f == nil {
+		return nil, ErrInvalid
+	}
+	_, dirents, _, err := f.readdir(n, readdirDirEntry)
+	return dirents, err
 }
+
+// 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

src/os/dir_darwin.go

@@ -24,11 +24,11 @@ func (d *dirInfo) close() {
 	d.dir = 0
 }
 
-func (f *File) readdirnames(n int) (names []string, err error) {
+func (f *File) readdir(n int, mode readdirMode) (names []string, dirents []DirEntry, infos []FileInfo, err error) {
 	if f.dirinfo == nil {
 		dir, call, errno := f.pfd.OpenDir()
 		if errno != nil {
-			return nil, &PathError{call, f.name, errno}
+			return nil, nil, nil, &PathError{Op: call, Path: f.name, Err: errno}
 		}
 		f.dirinfo = &dirInfo{
 			dir: dir,
@@ -42,15 +42,14 @@ func (f *File) readdirnames(n int) (names []string, err error) {
 		n = -1
 	}
 
-	names = make([]string, 0, size)
 	var dirent syscall.Dirent
 	var entptr *syscall.Dirent
-	for len(names) < size || n == -1 {
+	for len(names)+len(dirents)+len(infos) < size || n == -1 {
 		if errno := readdir_r(d.dir, &dirent, &entptr); errno != 0 {
 			if errno == syscall.EINTR {
 				continue
 			}
-			return names, &PathError{"readdir", f.name, errno}
+			return names, dirents, infos, &PathError{Op: "readdir", Path: f.name, Err: errno}
 		}
 		if entptr == nil { // EOF
 			break
@@ -69,13 +68,58 @@ func (f *File) readdirnames(n int) (names []string, err error) {
 		if string(name) == "." || string(name) == ".." {
 			continue
 		}
-		names = append(names, string(name))
+		if mode == readdirName {
+			names = append(names, string(name))
+		} else if mode == readdirDirEntry {
+			de, err := newUnixDirent(f.name, string(name), dtToType(dirent.Type))
+			if IsNotExist(err) {
+				// File disappeared between readdir and stat.
+				// Treat as if it didn't exist.
+				continue
+			}
+			if err != nil {
+				return nil, dirents, nil, err
+			}
+			dirents = append(dirents, de)
+		} else {
+			info, err := lstat(f.name + "/" + string(name))
+			if IsNotExist(err) {
+				// File disappeared between readdir + stat.
+				// Treat as if it didn't exist.
+				continue
+			}
+			if err != nil {
+				return nil, nil, infos, err
+			}
+			infos = append(infos, info)
+		}
 		runtime.KeepAlive(f)
 	}
-	if n >= 0 && len(names) == 0 {
-		return names, io.EOF
+
+	if n > 0 && len(names)+len(dirents)+len(infos) == 0 {
+		return nil, nil, nil, io.EOF
+	}
+	return names, dirents, infos, nil
+}
+
+func dtToType(typ uint8) FileMode {
+	switch typ {
+	case syscall.DT_BLK:
+		return ModeDevice
+	case syscall.DT_CHR:
+		return ModeDevice | ModeCharDevice
+	case syscall.DT_DIR:
+		return ModeDir
+	case syscall.DT_FIFO:
+		return ModeNamedPipe
+	case syscall.DT_LNK:
+		return ModeSymlink
+	case syscall.DT_REG:
+		return 0
+	case syscall.DT_SOCK:
+		return ModeSocket
 	}
-	return names, nil
+	return ^FileMode(0)
 }
 
 // Implemented in syscall/syscall_darwin.go.

src/os/dir_plan9.go

@@ -9,7 +9,7 @@ import (
 	"syscall"
 )
 
-func (file *File) readdir(n int) ([]FileInfo, error) {
+func (file *File) readdir(n int, mode readdirMode) (names []string, dirents []DirEntry, infos []FileInfo, err error) {
 	// If this file has no dirinfo, create one.
 	if file.dirinfo == nil {
 		file.dirinfo = new(dirInfo)
@@ -20,7 +20,6 @@ func (file *File) readdir(n int) ([]FileInfo, error) {
 		size = 100
 		n = -1
 	}
-	fi := make([]FileInfo, 0, size) // Empty with room to grow.
 	for n != 0 {
 		// Refill the buffer if necessary.
 		if d.bufp >= d.nbuf {
@@ -33,41 +32,50 @@ func (file *File) readdir(n int) ([]FileInfo, error) {
 				if err == io.EOF {
 					break
 				}
-				return fi, &PathError{"readdir", file.name, err}
+				return names, dirents, infos, &PathError{"readdir", file.name, err}
 			}
 			if nb < syscall.STATFIXLEN {
-				return fi, &PathError{"readdir", file.name, syscall.ErrShortStat}
+				return names, dirents, infos, &PathError{"readdir", file.name, syscall.ErrShortStat}
 			}
 		}
 
 		// Get a record from the buffer.
 		b := d.buf[d.bufp:]
 		m := int(uint16(b[0])|uint16(b[1])<<8) + 2
 		if m < syscall.STATFIXLEN {
-			return fi, &PathError{"readdir", file.name, syscall.ErrShortStat}
+			return names, dirents, infos, &PathError{"readdir", file.name, syscall.ErrShortStat}
 		}
 
 		dir, err := syscall.UnmarshalDir(b[:m])
 		if err != nil {
-			return fi, &PathError{"readdir", file.name, err}
+			return names, dirents, infos, &PathError{"readdir", file.name, err}
 		}
-		fi = append(fi, fileInfoFromStat(dir))
 
+		if mode == readdirName {
+			names = append(names, dir.Name)
+		} else {
+			f := fileInfoFromStat(dir)
+			if mode == readdirDirEntry {
+				dirents = append(dirents, dirEntry{f})
+			} else {
+				infos = append(infos, f)
+			}
+		}
 		d.bufp += m
 		n--
 	}
 
-	if n >= 0 && len(fi) == 0 {
-		return fi, io.EOF
+	if n > 0 && len(names)+len(dirents)+len(infos) == 0 {
+		return nil, nil, nil, io.EOF
 	}
-	return fi, nil
+	return names, dirents, infos, nil
 }
 
-func (file *File) readdirnames(n int) (names []string, err error) {
-	fi, err := file.Readdir(n)
-	names = make([]string, len(fi))
-	for i := range fi {
-		names[i] = fi[i].Name()
-	}
-	return
+type dirEntry struct {
+	fs *fileStat
 }
+
+func (de dirEntry) Name() string            { return de.fs.Name() }
+func (de dirEntry) IsDir() bool             { return de.fs.IsDir() }
+func (de dirEntry) Type() FileMode          { return de.fs.Mode().Type() }
+func (de dirEntry) Info() (FileInfo, error) { return de.fs, nil }