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