proposal: os: add ReparsePointTag

[qmuntal]

Proposal Details

Windows applications might need to know the reparse point tag of a given os.FileInfo. Although the Windows implementation of os.FileInfo knows the reparse point tag, there is no way to get that information using the public os API. This means that applications are forced to partially reimplement os.Lstat by opening the file and calling GetFileInformationByHandleEx.

I propose to add the following helper function to the os package:

// ReparsePointTag returns the the reparse point tag associated with fi.
//
// ReparsePointTag only applies to results returned by this package's [LStat].
// fi must be associated with a reparse point.
// Otherwise, ReparsePointTag returns false.
func ReparsePointTag(fi FileInfo) (uint32, bool)

The ReparsePointTag implementation could be made more os-agnostic by also defining an interface that external os.FileInfo implementations could implement to get the reparse point tag. This might be an overkill for now, as reparse points are not a broadly-addopted concept outside NTFS file systems.

ReparsePointTag would only be useful on Windows for now, although it could potentially be implemented on other OSes supporting NTFS drivers.

@golang/windows

[earthboundkid]

This is a Windows specific concept and does not belong in the os package. It could go in a syscall package however.

[ianlancetaylor]

It seems hard to put this proposed function in any package other than the os package, because it would have to interrogate the unexported Windows-specific fileStat.

That said I also wonder whether there is some way to handle this general idea outside the os package.

[mateusz834]

It seems hard to put this proposed function in any package other than the os package, because it would have to interrogate the unexported Windows-specific fileStat.

The unexported struct can be moved to an internal/ package. (and it can be exported then)

[qmuntal]

The unexported struct can be moved to an internal/ package. (and it can be exported then)

Which would be de input of the syscall function? syscall can't depend on os, so it can't accept a os.FileInfo.

[mateusz834]

@qmuntal I have not checked it, but what about fs.FileInfo? os.FileInfo is an alias now.

EDIT: io/fs imports time which imports syscall, so not possible.

[earthboundkid]

The unexported struct can be moved to an internal/ package. (and it can be exported then)

Which would be de input of the syscall function? syscall can't depend on os, so it can't accept a os.FileInfo.

I don't understand how these work or what they actually do, but surely it comes back to some FD or Windows equivalent which you can pull out of FileInfo.Sys()?

[apparentlymart]

I think the point here is that the requested information has already been retrieved from the OS by the time the caller is holding the os.FileInfo object:

go/src/os/types_windows.go

Lines 46 to 79 in 6705ac6

	func newFileStatFromGetFileInformationByHandle(path string, h syscall.Handle) (fs *fileStat, err error) {
	var d syscall.ByHandleFileInformation
	err = syscall.GetFileInformationByHandle(h, &d)
	if err != nil {
	return nil, &PathError{Op: "GetFileInformationByHandle", Path: path, Err: err}
	}
	var reparseTag uint32
	if d.FileAttributes&syscall.FILE_ATTRIBUTE_REPARSE_POINT != 0 {
	var ti windows.FILE_ATTRIBUTE_TAG_INFO
	err = windows.GetFileInformationByHandleEx(h, windows.FileAttributeTagInfo, (*byte)(unsafe.Pointer(&ti)), uint32(unsafe.Sizeof(ti)))
	if err != nil {
	return nil, &PathError{Op: "GetFileInformationByHandleEx", Path: path, Err: err}
	}
	reparseTag = ti.ReparseTag
	}
	return &fileStat{
	name: filepathlite.Base(path),
	FileAttributes: d.FileAttributes,
	CreationTime: d.CreationTime,
	LastAccessTime: d.LastAccessTime,
	LastWriteTime: d.LastWriteTime,
	FileSizeHigh: d.FileSizeHigh,
	FileSizeLow: d.FileSizeLow,
	vol: d.VolumeSerialNumber,
	idxhi: d.FileIndexHigh,
	idxlo: d.FileIndexLow,
	ReparseTag: reparseTag,
	// fileStat.path is used by os.SameFile to decide if it needs
	// to fetch vol, idxhi and idxlo. But these are already set,
	// so set fileStat.path to "" to prevent os.SameFile doing it again.
	}, nil
	}

Note that ReparseTag is stored as a field of this object, but it's returned as an os.FileInfo interface value and since the type is unexported there is no way to type-assert from outside the package to get at it.

Edit: Whoops... submitted to early. 🙄

It seems like this could therefore be exported as a new field of the syscall.Win32FileAttributeData returned by Sys as @earthboundkid suggested:

go/src/os/types_windows.go

Lines 276 to 285 in 6705ac6

	func (fs *fileStat) Sys() any {
	return &syscall.Win32FileAttributeData{
	FileAttributes: fs.FileAttributes,
	CreationTime: fs.CreationTime,
	LastAccessTime: fs.LastAccessTime,
	LastWriteTime: fs.LastWriteTime,
	FileSizeHigh: fs.FileSizeHigh,
	FileSizeLow: fs.FileSizeLow,
	}
	}

[qmuntal]

It seems like this could therefore be exported as a new field of the syscall.Win32FileAttributeData returned by Sys as @earthboundkid suggested:

That was also my initial thought, but I worry that we will confuse users that legitimately uses syscall.Win32FileAttributeData as an argument to syscall.GetFileAttributesEx (which was the original usage of that type). They will see that there are some properties passed to the Win32 call which are never populated. There are a few projects using it in this way: https://github.com/search?q=%22var+fa+syscall.Win32FileAttributeData%22+language%3AGo+NOT+is%3Afork&type=code.

But maybe it's fine given that these projects should be using golang.org/x/sys.Win32FileAttributeData instead.

[ianlancetaylor]

Is syscall.Win32FileAttributeData a standard Windows type, or is it something we invented for Go?

[qmuntal]

It is a standard Windows type: https://learn.microsoft.com/en-us/windows/win32/api/fileapi/ns-fileapi-win32_file_attribute_data.