Source file src/os/dir.go
1 // Copyright 2016 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 package os 6 7 import ( 8 "internal/safefilepath" 9 "io" 10 "io/fs" 11 "sort" 12 ) 13 14 type readdirMode int 15 16 const ( 17 readdirName readdirMode = iota 18 readdirDirEntry 19 readdirFileInfo 20 ) 21 22 // Readdir reads the contents of the directory associated with file and 23 // returns a slice of up to n [FileInfo] values, as would be returned 24 // by [Lstat], in directory order. Subsequent calls on the same file will yield 25 // further FileInfos. 26 // 27 // If n > 0, Readdir returns at most n FileInfo structures. In this case, if 28 // Readdir returns an empty slice, it will return a non-nil error 29 // explaining why. At the end of a directory, the error is [io.EOF]. 30 // 31 // If n <= 0, Readdir returns all the FileInfo from the directory in 32 // a single slice. In this case, if Readdir succeeds (reads all 33 // the way to the end of the directory), it returns the slice and a 34 // nil error. If it encounters an error before the end of the 35 // directory, Readdir returns the FileInfo read until that point 36 // and a non-nil error. 37 // 38 // Most clients are better served by the more efficient ReadDir method. 39 func (f *File) Readdir(n int) ([]FileInfo, error) { 40 if f == nil { 41 return nil, ErrInvalid 42 } 43 _, _, infos, err := f.readdir(n, readdirFileInfo) 44 if infos == nil { 45 // Readdir has historically always returned a non-nil empty slice, never nil, 46 // even on error (except misuse with nil receiver above). 47 // Keep it that way to avoid breaking overly sensitive callers. 48 infos = []FileInfo{} 49 } 50 return infos, err 51 } 52 53 // Readdirnames reads the contents of the directory associated with file 54 // and returns a slice of up to n names of files in the directory, 55 // in directory order. Subsequent calls on the same file will yield 56 // further names. 57 // 58 // If n > 0, Readdirnames returns at most n names. In this case, if 59 // Readdirnames returns an empty slice, it will return a non-nil error 60 // explaining why. At the end of a directory, the error is [io.EOF]. 61 // 62 // If n <= 0, Readdirnames returns all the names from the directory in 63 // a single slice. In this case, if Readdirnames succeeds (reads all 64 // the way to the end of the directory), it returns the slice and a 65 // nil error. If it encounters an error before the end of the 66 // directory, Readdirnames returns the names read until that point and 67 // a non-nil error. 68 func (f *File) Readdirnames(n int) (names []string, err error) { 69 if f == nil { 70 return nil, ErrInvalid 71 } 72 names, _, _, err = f.readdir(n, readdirName) 73 if names == nil { 74 // Readdirnames has historically always returned a non-nil empty slice, never nil, 75 // even on error (except misuse with nil receiver above). 76 // Keep it that way to avoid breaking overly sensitive callers. 77 names = []string{} 78 } 79 return names, err 80 } 81 82 // A DirEntry is an entry read from a directory 83 // (using the [ReadDir] function or a [File.ReadDir] method). 84 type DirEntry = fs.DirEntry 85 86 // ReadDir reads the contents of the directory associated with the file f 87 // and returns a slice of [DirEntry] values in directory order. 88 // Subsequent calls on the same file will yield later DirEntry records in the directory. 89 // 90 // If n > 0, ReadDir returns at most n DirEntry records. 91 // In this case, if ReadDir returns an empty slice, it will return an error explaining why. 92 // At the end of a directory, the error is [io.EOF]. 93 // 94 // If n <= 0, ReadDir returns all the DirEntry records remaining in the directory. 95 // When it succeeds, it returns a nil error (not io.EOF). 96 func (f *File) ReadDir(n int) ([]DirEntry, error) { 97 if f == nil { 98 return nil, ErrInvalid 99 } 100 _, dirents, _, err := f.readdir(n, readdirDirEntry) 101 if dirents == nil { 102 // Match Readdir and Readdirnames: don't return nil slices. 103 dirents = []DirEntry{} 104 } 105 return dirents, err 106 } 107 108 // testingForceReadDirLstat forces ReadDir to call Lstat, for testing that code path. 109 // This can be difficult to provoke on some Unix systems otherwise. 110 var testingForceReadDirLstat bool 111 112 // ReadDir reads the named directory, 113 // returning all its directory entries sorted by filename. 114 // If an error occurs reading the directory, 115 // ReadDir returns the entries it was able to read before the error, 116 // along with the error. 117 func ReadDir(name string) ([]DirEntry, error) { 118 f, err := openDir(name) 119 if err != nil { 120 return nil, err 121 } 122 defer f.Close() 123 124 dirs, err := f.ReadDir(-1) 125 sort.Slice(dirs, func(i, j int) bool { return dirs[i].Name() < dirs[j].Name() }) 126 return dirs, err 127 } 128 129 // CopyFS copies the file system fsys into the directory dir, 130 // creating dir if necessary. 131 // 132 // Newly created directories and files have their default modes 133 // where any bits from the file in fsys that are not part of the 134 // standard read, write, and execute permissions will be zeroed 135 // out, and standard read and write permissions are set for owner, 136 // group, and others while retaining any existing execute bits from 137 // the file in fsys. 138 // 139 // Symbolic links in fsys are not supported, a *PathError with Err set 140 // to ErrInvalid is returned on symlink. 141 // 142 // Copying stops at and returns the first error encountered. 143 func CopyFS(dir string, fsys fs.FS) error { 144 return fs.WalkDir(fsys, ".", func(path string, d fs.DirEntry, err error) error { 145 if err != nil { 146 return err 147 } 148 149 fpath, err := safefilepath.Localize(path) 150 if err != nil { 151 return err 152 } 153 newPath := joinPath(dir, fpath) 154 if d.IsDir() { 155 return MkdirAll(newPath, 0777) 156 } 157 158 // TODO(panjf2000): handle symlinks with the help of fs.ReadLinkFS 159 // once https://go.dev/issue/49580 is done. 160 // we also need safefilepath.IsLocal from https://go.dev/cl/564295. 161 if !d.Type().IsRegular() { 162 return &PathError{Op: "CopyFS", Path: path, Err: ErrInvalid} 163 } 164 165 r, err := fsys.Open(path) 166 if err != nil { 167 return err 168 } 169 defer r.Close() 170 info, err := r.Stat() 171 if err != nil { 172 return err 173 } 174 w, err := OpenFile(newPath, O_CREATE|O_TRUNC|O_WRONLY, 0666|info.Mode()&0777) 175 if err != nil { 176 return err 177 } 178 179 if _, err := io.Copy(w, r); err != nil { 180 w.Close() 181 return &PathError{Op: "Copy", Path: newPath, Err: err} 182 } 183 return w.Close() 184 }) 185 } 186