FileInfo/DirectoryInfo: enable transparent handling of symbolic links

[tmds]

Background and Motivation

Users may not be aware that the fileName/path they are providing is a symbolic link.

This proposal makes it possible to operate on such path without the user having to manually handle symbolic links using the APIs added in #24271.

Proposed API

A new constructor on FileInfo allows to specify whether the instance should return information about the target instead of the symbolic link.

class FileInfo
{
   public FileInfo(string fileName, bool followLinks) { }
}
class DirectoryInfo
{
    public DirectoryInfo(string path, bool followLinks) { }
}

The argument causes information for the link target to be returned for the following properties. When there is no target they throw no such file.

class FileInfo
{
    public bool IsReadOnly { get { throw null; } set { } }
    public long Length { get { throw null; } }
}
class FileSystemInfo
{
    public FileAttributes Attributes { get { throw null; } set { } }
    public DateTime CreationTime { get { throw null; } set { } }
    public DateTime CreationTimeUtc { get { throw null; } set { } }
    public abstract bool Exists { get; }
    public DateTime LastAccessTime { get { throw null; } set { } }
    public DateTime LastAccessTimeUtc { get { throw null; } set { } }
    public DateTime LastWriteTime { get { throw null; } set { } }
    public DateTime LastWriteTimeUtc { get { throw null; } set { } }

    // from https://github.com/dotnet/runtime/issues/24271
    // always returns `false` when `followLinks` is `true`.
    public bool IsSymbolicLink { get; } 
}

It does not affect the following operations. Which are either:

• always working on the target, or
• working on the 'fileName'/'path' argument.

class DirectoryInfo
{
    // applies to 'path':
    public DirectoryInfo? Parent { get { throw null; } }
    public DirectoryInfo Root { get { throw null; } }

    // applies to 'target':
    public void Create() { }
    public DirectoryInfo CreateSubdirectory(string path) { throw null; }
    public IEnumerable<DirectoryInfo> EnumerateDirectories() { throw null; }
    public IEnumerable<DirectoryInfo> EnumerateDirectories(string searchPattern) { throw null; }
    public IEnumerable<DirectoryInfo> EnumerateDirectories(string searchPattern, EnumerationOptions enumerationOptions) { throw null; }
    public IEnumerable<DirectoryInfo> EnumerateDirectories(string searchPattern, SearchOption searchOption) { throw null; }
    public IEnumerable<FileInfo> EnumerateFiles() { throw null; }
    public IEnumerable<FileInfo> EnumerateFiles(string searchPattern) { throw null; }
    public IEnumerable<FileInfo> EnumerateFiles(string searchPattern, EnumerationOptions enumerationOptions) { throw null; }
    public IEnumerable<FileInfo> EnumerateFiles(string searchPattern, SearchOption searchOption) { throw null; }
    public IEnumerable<FileSystemInfo> EnumerateFileSystemInfos() { throw null; }
    public IEnumerable<FileSystemInfo> EnumerateFileSystemInfos(string searchPattern) { throw null; }
    public IEnumerable<FileSystemInfo> EnumerateFileSystemInfos(string searchPattern, EnumerationOptions enumerationOptions) { throw null; }
    public IEnumerable<FileSystemInfo> EnumerateFileSystemInfos(string searchPattern, SearchOption searchOption) { throw null; }
    public DirectoryInfo[] GetDirectories() { throw null; }
    public DirectoryInfo[] GetDirectories(string searchPattern) { throw null; }
    public DirectoryInfo[] GetDirectories(string searchPattern, EnumerationOptions enumerationOptions) { throw null; }
    public DirectoryInfo[] GetDirectories(string searchPattern, SearchOption searchOption) { throw null; }
    public FileInfo[] GetFiles() { throw null; }
    public FileInfo[] GetFiles(string searchPattern) { throw null; }
    public FileInfo[] GetFiles(string searchPattern, EnumerationOptions enumerationOptions) { throw null; }
    public FileInfo[] GetFiles(string searchPattern, SearchOption searchOption) { throw null; }
    public FileSystemInfo[] GetFileSystemInfos() { throw null; }
    public FileSystemInfo[] GetFileSystemInfos(string searchPattern) { throw null; }
    public FileSystemInfo[] GetFileSystemInfos(string searchPattern, EnumerationOptions enumerationOptions) { throw null; }
    public FileSystemInfo[] GetFileSystemInfos(string searchPattern, SearchOption searchOption) { throw null; }

    // applies to 'path':
    public void Delete(bool recursive) { }
    public override void Delete() { }
    public void MoveTo(string destDirName) { }
}
class FileInfo
{
    // applies to 'fileName'
    public DirectoryInfo? Directory { get { throw null; } }
    public string? DirectoryName { get { throw null; } }

    // applies to 'target':
    public StreamWriter AppendText() { throw null; }
    public FileInfo CopyTo(string destFileName) { throw null; }
    public FileInfo CopyTo(string destFileName, bool overwrite) { throw null; }
    public FileStream Create() { throw null; }
    public StreamWriter CreateText() { throw null; }
    public void Decrypt() { }
    public void Encrypt() { }
    public FileStream Open(FileMode mode) { throw null; }
    public FileStream Open(FileMode mode, FileAccess access) { throw null; }
    public FileStream Open(FileMode mode, FileAccess access, FileShare share) { throw null; }
    public FileStream OpenRead() { throw null; }
    public StreamReader OpenText() { throw null; }
    public FileStream OpenWrite() { throw null; }
    public FileInfo Replace(string destinationFileName, string? destinationBackupFileName) { throw null; }
    public FileInfo Replace(string destinationFileName, string? destinationBackupFileName, bool ignoreMetadataErrors) { throw null; }

    // applies to 'path':
    public override void Delete() { }
    public void MoveTo(string destFileName) { }
    public void MoveTo(string destFileName, bool overwrite) { }
}
class FileSystemInfo
{
    // applies to 'fileName'/'path':
    protected string FullPath;
    protected string OriginalPath;
    public string Extension { get { throw null; } }
    public virtual string FullName { get { throw null; } }
    public abstract string Name { get; }
}

Usage Examples

FileInfo file = new FileInfo("/tmp/my-file", followLinks: true);
DateTime lastWriteTime = file.LastWriteTimeUtc;
while (true)
{
    Thread.Sleep(1000);
    file.Refresh();
    DateTime writeTime = file.LastWriteTimeUtc;
    if (writeTime != lastWriteTime)
    {
        Console.WriteLine("The file has changed");
        lastWriteTime = writeTime;
    }
}

Implementation

On Linux, this means the information for the properties is retrieved using stat instead of vstat.
For Delete, the final target is first located, e.g. by calling realpath, and that is then deleted.

edits:

• added IsSymbolicLink from Proposed API for symbolic links #24271
• renamed followLink to followLinks.
• updated proposal to make Delete target based.
• added implementation section which covers Linux
• revert Delete to be path based again.
• place MoveTo under path-based

Tagging subscribers to this area: @carlossanlop
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and Motivation

Users may not be aware that the fileName/path they are providing is a symbolic link.

This proposal makes it possible to operate on such path without the user having to manually handle symbolic links using the APIs added in #24271.

Proposed API

A new constructor on FileInfo allows to specify whether the instance should return information about the target instead of the symbolic link.

class FileInfo
{
   public FileInfo(string fileName, bool followLink) { }
}
class DirectoryInfo
{
    public DirectoryInfo(string path, bool followLink) { }
}

The argument causes information for the link target to be returned for the following properties:

class FileInfo
{
    public bool IsReadOnly { get { throw null; } set { } }
    public long Length { get { throw null; } }
}
class FileSystemInfo
{
    public FileAttributes Attributes { get { throw null; } set { } }
    public DateTime CreationTime { get { throw null; } set { } }
    public DateTime CreationTimeUtc { get { throw null; } set { } }
    public abstract bool Exists { get; }
    public DateTime LastAccessTime { get { throw null; } set { } }
    public DateTime LastAccessTimeUtc { get { throw null; } set { } }
    public DateTime LastWriteTime { get { throw null; } set { } }
    public DateTime LastWriteTimeUtc { get { throw null; } set { } }
}

It does not affect the following operations. Which are either:

• always working on the target, or
• working on the 'fileName'/'path' argument.

class DirectoryInfo
{
    // applies to 'path':
    public DirectoryInfo? Parent { get { throw null; } }
    public DirectoryInfo Root { get { throw null; } }

    // applies to 'target':
    public void Create() { }
    public DirectoryInfo CreateSubdirectory(string path) { throw null; }
    public void Delete(bool recursive) { }
    public IEnumerable<DirectoryInfo> EnumerateDirectories() { throw null; }
    public IEnumerable<DirectoryInfo> EnumerateDirectories(string searchPattern) { throw null; }
    public IEnumerable<DirectoryInfo> EnumerateDirectories(string searchPattern, EnumerationOptions enumerationOptions) { throw null; }
    public IEnumerable<DirectoryInfo> EnumerateDirectories(string searchPattern, SearchOption searchOption) { throw null; }
    public IEnumerable<FileInfo> EnumerateFiles() { throw null; }
    public IEnumerable<FileInfo> EnumerateFiles(string searchPattern) { throw null; }
    public IEnumerable<FileInfo> EnumerateFiles(string searchPattern, EnumerationOptions enumerationOptions) { throw null; }
    public IEnumerable<FileInfo> EnumerateFiles(string searchPattern, SearchOption searchOption) { throw null; }
    public IEnumerable<FileSystemInfo> EnumerateFileSystemInfos() { throw null; }
    public IEnumerable<FileSystemInfo> EnumerateFileSystemInfos(string searchPattern) { throw null; }
    public IEnumerable<FileSystemInfo> EnumerateFileSystemInfos(string searchPattern, EnumerationOptions enumerationOptions) { throw null; }
    public IEnumerable<FileSystemInfo> EnumerateFileSystemInfos(string searchPattern, SearchOption searchOption) { throw null; }
    public DirectoryInfo[] GetDirectories() { throw null; }
    public DirectoryInfo[] GetDirectories(string searchPattern) { throw null; }
    public DirectoryInfo[] GetDirectories(string searchPattern, EnumerationOptions enumerationOptions) { throw null; }
    public DirectoryInfo[] GetDirectories(string searchPattern, SearchOption searchOption) { throw null; }
    public FileInfo[] GetFiles() { throw null; }
    public FileInfo[] GetFiles(string searchPattern) { throw null; }
    public FileInfo[] GetFiles(string searchPattern, EnumerationOptions enumerationOptions) { throw null; }
    public FileInfo[] GetFiles(string searchPattern, SearchOption searchOption) { throw null; }
    public FileSystemInfo[] GetFileSystemInfos() { throw null; }
    public FileSystemInfo[] GetFileSystemInfos(string searchPattern) { throw null; }
    public FileSystemInfo[] GetFileSystemInfos(string searchPattern, EnumerationOptions enumerationOptions) { throw null; }
    public FileSystemInfo[] GetFileSystemInfos(string searchPattern, SearchOption searchOption) { throw null; }
    public void MoveTo(string destDirName) { }

    // applies to 'path':
    public override void Delete() { }
}
class FileInfo
{
    // applies to 'fileName'
    public DirectoryInfo? Directory { get { throw null; } }
    public string? DirectoryName { get { throw null; } }

    // applies to 'target':
    public StreamWriter AppendText() { throw null; }
    public FileInfo CopyTo(string destFileName) { throw null; }
    public FileInfo CopyTo(string destFileName, bool overwrite) { throw null; }
    public FileStream Create() { throw null; }
    public StreamWriter CreateText() { throw null; }
    public void Decrypt() { }
    public void Encrypt() { }
    public void MoveTo(string destFileName) { }
    public void MoveTo(string destFileName, bool overwrite) { }
    public FileStream Open(FileMode mode) { throw null; }
    public FileStream Open(FileMode mode, FileAccess access) { throw null; }
    public FileStream Open(FileMode mode, FileAccess access, FileShare share) { throw null; }
    public FileStream OpenRead() { throw null; }
    public StreamReader OpenText() { throw null; }
    public FileStream OpenWrite() { throw null; }
    public FileInfo Replace(string destinationFileName, string? destinationBackupFileName) { throw null; }
    public FileInfo Replace(string destinationFileName, string? destinationBackupFileName, bool ignoreMetadataErrors) { throw null; }

    // applies to 'fileName':
    public override void Delete() { }
}
class FileSystemInfo
{
    // applies to 'fileName'/'path':
    protected string FullPath;
    protected string OriginalPath;
    public string Extension { get { throw null; } }
    public virtual string FullName { get { throw null; } }
    public abstract string Name { get; }
}

Usage Examples

FileInfo file = new FileInfo("/tmp/my-file", followLink: true);
DateTime lastWriteTime = file.LastWriteTimeUtc;
while (true)
{
    Thread.Sleep(1000);
    file.Refresh();
    DateTime writeTime = file.LastWriteTimeUtc;
    if (writeTime != lastWriteTime)
    {
        Console.WriteLine("The file has changed");
        lastWriteTime = writeTime;
    }
}

Author:	tmds
Assignees:	-
Labels:	api-suggestion, area-System.IO, untriaged
Milestone:	-

[mklement0]

While I (now) definitely like the idea in principle, I think it is problematic to create hybrid FileSystemInfo instances that combine properties of the link (.Name, .FullName, ...) with properties of its target.

I think it is cleaner to simply return the target's FileSystemInfo representation.

Also, we should flesh out the following:

• What happens if the target doesn't exist?

  • The decision as to whether hybrid instances should or shouldn't be constructed probably impacts this question.

• What is the implied recursion mode of followLink: true?

  • (a) One-step (non-recursive) resolution (which may give you yet _another link).
  • Recursive resolution can have two behaviors:
    (b) Recurse until the leaf component of the target path no longer represents a link.
    (c) Recurse until the target path contains no link components at all, i.e. until the target's canonical path has been determined.
  • Follow-up question: is a bool value therefore enough, or do all of these modes need to be supported explicitly.

(a) generally wouldn't be enough to support your use case, while (b) would.

On the other hand, (c) is usually supported by a single platform-native call, such as GetFinalPathNameByHandle on Windows and realpath() function on Unix-like platforms , so from a performance perspective it may be preferable.

[tmds]

I think it is problematic to create hybrid FileSystemInfo instances that combine properties of the link (.Name, .FullName, ...) with properties of its target.

I don't think this is problematic. I think it is desired to not expose a symlink was involved.
The path that is passed to the constructor is treated as an invariant.

What happens if the target doesn't exist?

No such file exception.

What is the implied recursion mode of followLink: true?

Return information about the final target.

On the other hand, (c) is usually supported by a single platform-native call, such as GetFinalPathNameByHandle on Windows and realpath() function on Unix-like platforms , so from a performance perspective it may be preferable.

For Unix, it should be about using stat instead of lstat. I don't think we need realpath.
I don't know about Windows.

[iSazonov]

This seems less flexible and more confusing than #24271. Especially disturbing is that we set the behavior "before", but then we don't even know about it (i.e. if then there are two code paths, we can't choose the right one). In other words it's not so easy to implement the "find all symbolic links" scenario.

[tmds]

@iSazonov this is about working with files and directories regardless whether the path is or is not using a symbolic link.
#24271 is about working with symbolic links.
These are different use-cases.

[mklement0]

Agreed, @tmds; this proposal complements #24271.

However, I think the proposed hybrid file-info approach is problematic, because it violates a fundamental assumption: that the properties of a given FileSystemInfo represent the file-system entry pointed to by its path.

As proposed, one wouldn't be able to tell whether a given FileSystemInfo instance reflects the link's or the target's properties (except indirectly, by looking for the ReparsePoint attribute - but that means that such a hybrid instance them misrepresent its path as not being a symlink).

While more expensive, I suggest that the followSymlink: true constructor return a FileSystemInfo instance representing the (ultimate, non-link) target (in full).

• It is more expensive, because the stat system call, while capable of recursively locating the ultimate non-link target's metadata, doesn't support reporting the ultimate target's name and path.

• However, it should be possible to derive the name and path from the target's inode number

  • Not sure about the details and whether the path derived this way would be canonical, but arguably this aspect is incidental to the use case.

• I'm unclear on what the Windows equivalent would be.

[tmds]

However, I think the proposed hybrid file-info approach is problematic, because it violates a fundamental assumption: that the properties of a given FileSystemInfo represent the file-system entry pointed to by its path.

How should these properties behave when the path does not exist, or when the link is broken?
Should these properties update on Refresh?

I think it is valid for these properties to reflect the path that was passed to the constructor and maintain the behavior that has always existed here. Changing that can also cause problems.

If the final target is desired, maybe add a property for that. For example: string RealPath { get; } (which can call realpath on Linux).

As proposed, one wouldn't be able to tell whether a given FileSystemInfo instance reflects the link's or the target's properties

They reflect the target independent of whether the path is a link or not.

[mklement0]

How should these properties behave when the path does not exist, or when the link is broken?
Should these properties update on Refresh?

I don't understand the questions.
My proposal is:

• As before, a FileSystemInfo instance should only ever reflect the specific item targeted and its own properties, whatever its type (file, directory, or link to either) - I'm leaving the muddled .Exists behavior aside.

• Thus, setting followLink to true would simply return a FileSystemInfo instance representing the (ultimate, non-link) target, as if that target had been requested directly.

They reflect the target independent of whether the path is a link or not.

If I ask for link ./foo with followLink = true, and the resulting FileInfo instance then tells me that ./foo isn't a link, that is a problem.
Generally, if you are given a FileSystemInfo instance, you shouldn't have to guess at / investigate whether its properties are a 1:1 or a a hybrid representation.

If the final target is desired

I think it's fine to leave this use case to the APIs proposed in #24271, along the lines of .Get[Link]Target(returnFinalTarget: true)

[tmds]

Thus, setting followLink to true would simply return a FileSystemInfo instance representing the (ultimate, non-link) target, as if that target had been requested directly.

So the constructor throws if the path does not exist, or the link is broken?
And Refresh would be performed against the target path?

If I ask for link ./foo with followLink = true, and the resulting FileInfo instance then tells me that ./foo isn't a link, that is a problem.

I don't understand the problem. followLink is meant to make the properties reflect the target of the link, not the link itself.

you shouldn't have to guess at / investigate whether its properties are a 1:1 or a a hybrid representation.

Some properties are proposed to keep matching the path that was passed to the constructor. There is no guessing.

[mklement0]

So the constructor throws if the path does not exist, or the link is broken?

• If the target doesn't exist: That makes sense to me, and I thought it was also what you were proposing.

• If the input path doesn't exist: That also makes sense to me, given that setting followLink to true can be construed as having the expectation of an existing item.

And Refresh would be performed against the target path?

Yes, given that what I'm suggesting means that the resulting FileSystemInfo represent the target only. In other words: you use the link path solely to obtain the target information - the link is then completely out of the picture.

There is no guessing.

There is situational guessing / the need for investigating, if you're handed a preexisting FileSystemInfo instance.

followLink is meant to make the properties reflect the target of the link, not the link itself.

Indeed, and that includes Name, FullPath, ... and all related methods - in short: you are then unequivocally operating on the target.