os: document that fs.ReadDirFile.ReadDir doesn't restart each time

[hajimehoshi]

Go version

go version go1.22.6 darwin/arm64

Output of go env in your module/workspace:

GO111MODULE=''
GOARCH='arm64'
GOBIN=''
GOCACHE='/Users/hajimehoshi/Library/Caches/go-build'
GOENV='/Users/hajimehoshi/Library/Application Support/go/env'
GOEXE=''
GOEXPERIMENT=''
GOFLAGS=''
GOHOSTARCH='arm64'
GOHOSTOS='darwin'
GOINSECURE=''
GOMODCACHE='/Users/hajimehoshi/go/pkg/mod'
GONOPROXY=''
GONOSUMDB=''
GOOS='darwin'
GOPATH='/Users/hajimehoshi/go'
GOPRIVATE=''
GOPROXY='https://proxy.golang.org,direct'
GOROOT='/usr/local/go'
GOSUMDB='sum.golang.org'
GOTMPDIR=''
GOTOOLCHAIN='auto'
GOTOOLDIR='/usr/local/go/pkg/tool/darwin_arm64'
GOVCS=''
GOVERSION='go1.22.6'
GCCGO='gccgo'
AR='ar'
CC='clang'
CXX='clang++'
CGO_ENABLED='1'
GOMOD='/dev/null'
GOWORK=''
CGO_CFLAGS='-O2 -g'
CGO_CPPFLAGS=''
CGO_CXXFLAGS='-O2 -g'
CGO_FFLAGS='-O2 -g'
CGO_LDFLAGS='-O2 -g'
PKG_CONFIG='pkg-config'
GOGCCFLAGS='-fPIC -arch arm64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -ffile-prefix-map=/var/folders/cj/73zbb35j0qx5t4b6rnqq0__h0000gn/T/go-build3027760310=/tmp/go-build -gno-record-gcc-switches -fno-common'

What did you do?

Run this program

package main

import (
	"fmt"
	"io/fs"
	"os"
)

func main() {
	fmt.Println("-- os.Open --")
	{
		dir, err := os.Open("/")
		if err != nil {
			panic(err)
		}
		for i := 0; i < 3; i++ {
			ents, err := dir.ReadDir(0)
			if err != nil {
				panic(err)
			}
			fmt.Println(ents)
		}
	}

	fmt.Println("-- os.DirFS.Open --")
	{
		dir, err := os.DirFS("/").Open(".")
		if err != nil {
			panic(err)
		}
		for i := 0; i < 3; i++ {
			ents, err := dir.(fs.ReadDirFile).ReadDir(0)
			if err != nil {
				panic(err)
			}
			fmt.Println(ents)
		}
	}
}

What did you see happen?

I could reproduce the issue on my local macOS machine and the playground.

On the playground (https://go.dev/play/p/tBUins57hF-),

-- os.Open --
[d tmpfs/ d home/ d bin/ d var/ d etc/ d lib/ d tmp/ L lib64 d root/ d dev/ d usr/ d sys/ d proc/ - .dockerenv]
[]
[]
-- os.DirFS.Open --
[d tmpfs/ d home/ d bin/ d var/ d etc/ d lib/ d tmp/ L lib64 d root/ d dev/ d usr/ d sys/ d proc/ - .dockerenv]
[]
[]

What did you expect to see?

-- os.Open --
[d tmpfs/ d home/ d bin/ d var/ d etc/ d lib/ d tmp/ L lib64 d root/ d dev/ d usr/ d sys/ d proc/ - .dockerenv]
[]
[]
-- os.DirFS.Open --
[d tmpfs/ d home/ d bin/ d var/ d etc/ d lib/ d tmp/ L lib64 d root/ d dev/ d usr/ d sys/ d proc/ - .dockerenv]
[d tmpfs/ d home/ d bin/ d var/ d etc/ d lib/ d tmp/ L lib64 d root/ d dev/ d usr/ d sys/ d proc/ - .dockerenv]
[d tmpfs/ d home/ d bin/ d var/ d etc/ d lib/ d tmp/ L lib64 d root/ d dev/ d usr/ d sys/ d proc/ - .dockerenv]

os.File's ReadDir works as expected.

If n <= 0, ReadDir returns all the DirEntry records remaining in the directory. When it succeeds, it returns a nil error (not io.EOF).

On the other hand, the document for fs.ReadDirFile says

	// If n <= 0, ReadDir returns all the DirEntry values from the directory
	// in a single slice. In this case, if ReadDir succeeds (reads all the way
	// to the end of the directory), it returns the slice and a nil error.
	// If it encounters an error before the end of the directory,
	// ReadDir returns the DirEntry list read until that point and a non-nil error.

so ReadDir should return all the entries whatever the internal offset is, shouldn't it?

[gabyhelp]

Related Issues and Documentation

• Question about readdirnames function #33428 (closed)
• Readdirnames does not behave according to documentation #36984 (closed)
• os: small-count Readdirnames followed by seek-to-zero can lead to duplicate names #37161 (closed)
• os: dirFS.ReadFile returns inconsistent PathError.Path #64366 (closed)
• archive/{zip,tar}: (*Writer).AddFS omits empty directories #66831
• os: DirFS has interaction with Chdir #47214 (closed)
• os: os.DirFS doesn't work with Windows UNC paths #54694 (closed)
• io/fs,os: fs.ReadDir with an os.DirFS can produce invalid paths #44166 (closed)
• os: File.Seek() not resetting directory reads on MacOS Catalina #35767 (closed)
• archive/zip: duplicate entries in FS interface #45345 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[ianlancetaylor]

The docs for fs.ReadDirFile also say "Subsequent calls on the same file will yield further DirEntry values." This is working as expected.

I'll leave the issue open in case someone wants to clarify the docs.

[13mtfb]

I'll happily clarify the docs

[gopherbot]

Change https://go.dev/cl/663215 mentions this issue: fs: clarify documentation for ReadDir method