dir_windows.go

     1  // Copyright 2009 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/syscall/windows"
     9  	"io"
    10  	"io/fs"
    11  	"runtime"
    12  	"sync"
    13  	"syscall"
    14  	"unsafe"
    15  )
    16  
    17  // Auxiliary information if the File describes a directory
    18  type dirInfo struct {
    19  	mu sync.Mutex
    20  	// buf is a slice pointer so the slice header
    21  	// does not escape to the heap when returning
    22  	// buf to dirBufPool.
    23  	buf   *[]byte // buffer for directory I/O
    24  	bufp  int     // location of next record in buf
    25  	h     syscall.Handle
    26  	vol   uint32
    27  	class uint32 // type of entries in buf
    28  	path  string // absolute directory path, empty if the file system supports FILE_ID_BOTH_DIR_INFO
    29  }
    30  
    31  const (
    32  	// dirBufSize is the size of the dirInfo buffer.
    33  	// The buffer must be big enough to hold at least a single entry.
    34  	// The filename alone can be 512 bytes (MAX_PATH*2), and the fixed part of
    35  	// the FILE_ID_BOTH_DIR_INFO structure is 105 bytes, so dirBufSize
    36  	// should not be set below 1024 bytes (512+105+safety buffer).
    37  	// Windows 8.1 and earlier only works with buffer sizes up to 64 kB.
    38  	dirBufSize = 64 * 1024 // 64kB
    39  )
    40  
    41  var dirBufPool = sync.Pool{
    42  	New: func() any {
    43  		// The buffer must be at least a block long.
    44  		buf := make([]byte, dirBufSize)
    45  		return &buf
    46  	},
    47  }
    48  
    49  func (d *dirInfo) close() {
    50  	d.h = 0
    51  	if d.buf != nil {
    52  		dirBufPool.Put(d.buf)
    53  		d.buf = nil
    54  	}
    55  }
    56  
    57  // allowReadDirFileID indicates whether File.readdir should try to use FILE_ID_BOTH_DIR_INFO
    58  // if the underlying file system supports it.
    59  // Useful for testing purposes.
    60  var allowReadDirFileID = true
    61  
    62  func (d *dirInfo) init(h syscall.Handle) {
    63  	d.h = h
    64  	d.class = windows.FileFullDirectoryRestartInfo
    65  	// The previous settings are enough to read the directory entries.
    66  	// The following code is only needed to support os.SameFile.
    67  
    68  	// It is safe to query d.vol once and reuse the value.
    69  	// Hard links are not allowed to reference files in other volumes.
    70  	// Junctions and symbolic links can reference files and directories in other volumes,
    71  	// but the reparse point should still live in the parent volume.
    72  	var flags uint32
    73  	err := windows.GetVolumeInformationByHandle(h, nil, 0, &d.vol, nil, &flags, nil, 0)
    74  	if err != nil {
    75  		d.vol = 0 // Set to zero in case Windows writes garbage to it.
    76  		// If we can't get the volume information, we can't use os.SameFile,
    77  		// but we can still read the directory entries.
    78  		return
    79  	}
    80  	if flags&windows.FILE_SUPPORTS_OBJECT_IDS == 0 {
    81  		// The file system does not support object IDs, no need to continue.
    82  		return
    83  	}
    84  	if allowReadDirFileID && flags&windows.FILE_SUPPORTS_OPEN_BY_FILE_ID != 0 {
    85  		// Use FileIdBothDirectoryRestartInfo if available as it returns the file ID
    86  		// without the need to open the file.
    87  		d.class = windows.FileIdBothDirectoryRestartInfo
    88  	} else {
    89  		// If FileIdBothDirectoryRestartInfo is not available but objects IDs are supported,
    90  		// get the directory path so that os.SameFile can use it to open the file
    91  		// and retrieve the file ID.
    92  		d.path, _ = windows.FinalPath(h, windows.FILE_NAME_OPENED)
    93  	}
    94  }
    95  
    96  func (file *File) readdir(n int, mode readdirMode) (names []string, dirents []DirEntry, infos []FileInfo, err error) {
    97  	// If this file has no dirInfo, create one.
    98  	var d *dirInfo
    99  	for {
   100  		d = file.dirinfo.Load()
   101  		if d != nil {
   102  			break
   103  		}
   104  		d = new(dirInfo)
   105  		d.init(file.pfd.Sysfd)
   106  		if file.dirinfo.CompareAndSwap(nil, d) {
   107  			break
   108  		}
   109  		// We lost the race: try again.
   110  		d.close()
   111  	}
   112  	d.mu.Lock()
   113  	defer d.mu.Unlock()
   114  	if d.buf == nil {
   115  		d.buf = dirBufPool.Get().(*[]byte)
   116  	}
   117  
   118  	wantAll := n <= 0
   119  	if wantAll {
   120  		n = -1
   121  	}
   122  	for n != 0 {
   123  		// Refill the buffer if necessary
   124  		if d.bufp == 0 {
   125  			err = windows.GetFileInformationByHandleEx(file.pfd.Sysfd, d.class, (*byte)(unsafe.Pointer(&(*d.buf)[0])), uint32(len(*d.buf)))
   126  			runtime.KeepAlive(file)
   127  			if err != nil {
   128  				if err == syscall.ERROR_NO_MORE_FILES {
   129  					// Optimization: we can return the buffer to the pool, there is nothing else to read.
   130  					dirBufPool.Put(d.buf)
   131  					d.buf = nil
   132  					break
   133  				}
   134  				if err == syscall.ERROR_FILE_NOT_FOUND &&
   135  					(d.class == windows.FileIdBothDirectoryRestartInfo || d.class == windows.FileFullDirectoryRestartInfo) {
   136  					// GetFileInformationByHandleEx doesn't document the return error codes when the info class is FileIdBothDirectoryRestartInfo,
   137  					// but MS-FSA 2.1.5.6.3 [1] specifies that the underlying file system driver should return STATUS_NO_SUCH_FILE when
   138  					// reading an empty root directory, which is mapped to ERROR_FILE_NOT_FOUND by Windows.
   139  					// Note that some file system drivers may never return this error code, as the spec allows to return the "." and ".."
   140  					// entries in such cases, making the directory appear non-empty.
   141  					// The chances of false positive are very low, as we know that the directory exists, else GetVolumeInformationByHandle
   142  					// would have failed, and that the handle is still valid, as we haven't closed it.
   143  					// See go.dev/issue/61159.
   144  					// [1] https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-fsa/fa8194e0-53ec-413b-8315-e8fa85396fd8
   145  					break
   146  				}
   147  				if s, _ := file.Stat(); s != nil && !s.IsDir() {
   148  					err = &PathError{Op: "readdir", Path: file.name, Err: syscall.ENOTDIR}
   149  				} else {
   150  					err = &PathError{Op: "GetFileInformationByHandleEx", Path: file.name, Err: err}
   151  				}
   152  				return
   153  			}
   154  			if d.class == windows.FileIdBothDirectoryRestartInfo {
   155  				d.class = windows.FileIdBothDirectoryInfo
   156  			} else if d.class == windows.FileFullDirectoryRestartInfo {
   157  				d.class = windows.FileFullDirectoryInfo
   158  			}
   159  		}
   160  		// Drain the buffer
   161  		var islast bool
   162  		for n != 0 && !islast {
   163  			var nextEntryOffset uint32
   164  			var nameslice []uint16
   165  			entry := unsafe.Pointer(&(*d.buf)[d.bufp])
   166  			if d.class == windows.FileIdBothDirectoryInfo {
   167  				info := (*windows.FILE_ID_BOTH_DIR_INFO)(entry)
   168  				nextEntryOffset = info.NextEntryOffset
   169  				nameslice = unsafe.Slice(&info.FileName[0], info.FileNameLength/2)
   170  			} else {
   171  				info := (*windows.FILE_FULL_DIR_INFO)(entry)
   172  				nextEntryOffset = info.NextEntryOffset
   173  				nameslice = unsafe.Slice(&info.FileName[0], info.FileNameLength/2)
   174  			}
   175  			d.bufp += int(nextEntryOffset)
   176  			islast = nextEntryOffset == 0
   177  			if islast {
   178  				d.bufp = 0
   179  			}
   180  			if (len(nameslice) == 1 && nameslice[0] == '.') ||
   181  				(len(nameslice) == 2 && nameslice[0] == '.' && nameslice[1] == '.') {
   182  				// Ignore "." and ".." and avoid allocating a string for them.
   183  				continue
   184  			}
   185  			name := syscall.UTF16ToString(nameslice)
   186  			if mode == readdirName {
   187  				names = append(names, name)
   188  			} else {
   189  				var f *fileStat
   190  				if d.class == windows.FileIdBothDirectoryInfo {
   191  					f = newFileStatFromFileIDBothDirInfo((*windows.FILE_ID_BOTH_DIR_INFO)(entry))
   192  				} else {
   193  					f = newFileStatFromFileFullDirInfo((*windows.FILE_FULL_DIR_INFO)(entry))
   194  					if d.path != "" {
   195  						// Defer appending the entry name to the parent directory path until
   196  						// it is really needed, to avoid allocating a string that may not be used.
   197  						// It is currently only used in os.SameFile.
   198  						f.appendNameToPath = true
   199  						f.path = d.path
   200  					}
   201  				}
   202  				f.name = name
   203  				f.vol = d.vol
   204  				if mode == readdirDirEntry {
   205  					dirents = append(dirents, dirEntry{f})
   206  				} else {
   207  					infos = append(infos, f)
   208  				}
   209  			}
   210  			n--
   211  		}
   212  	}
   213  	if !wantAll && len(names)+len(dirents)+len(infos) == 0 {
   214  		return nil, nil, nil, io.EOF
   215  	}
   216  	return names, dirents, infos, nil
   217  }
   218  
   219  type dirEntry struct {
   220  	fs *fileStat
   221  }
   222  
   223  func (de dirEntry) Name() string            { return de.fs.Name() }
   224  func (de dirEntry) IsDir() bool             { return de.fs.IsDir() }
   225  func (de dirEntry) Type() FileMode          { return de.fs.Mode().Type() }
   226  func (de dirEntry) Info() (FileInfo, error) { return de.fs, nil }
   227  
   228  func (de dirEntry) String() string {
   229  	return fs.FormatDirEntry(de)
   230  }
   231
View as plain text