Repository: go
Issue: os: document that fs.ReadDirFile.ReadDir doesn't restart each time
Labels: Documentation,help wanted,NeedsFix

### Go version

go version go1.22.6 darwin/arm64

### Output of `go env` in your module/workspace:

```shell
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

```go
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`](https://pkg.go.dev/os#File.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](https://pkg.go.dev/io/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?