Class FileUtils

Namespace

NanoByte.Common.Storage

Assembly

NanoByte.Common.dll

Provides filesystem-related helper methods.

public static class FileUtils

Inheritance

object

FileUtils

Methods

AreHardlinked(string, string)

Determines whether two files are hardlinked.

public static bool AreHardlinked(string path1, string path2)

Parameters

path1 string

The path of the first file.

path2 string

The path of the second file.

Returns

bool

Exceptions

IOException

There was an IO problem checking the files.

UnauthorizedAccessException

You have insufficient rights to check the files.

CanonicalizeAcl(ObjectSecurity)

Fixes ACLs that are not canonical (not ordered correctly).

public static void CanonicalizeAcl(this ObjectSecurity objectSecurity)

Parameters

objectSecurity ObjectSecurity

Create(string, long)

Creates or replaces a file. Pre-allocates the expected size of the file if possible.

public static FileStream Create(string path, long expectedSize)

Parameters

path string

The path of the file.

expectedSize long

The initial allocation size in bytes for the file.

Returns

FileStream

A stream for writing the file. No read access.

CreateHardlink(string, string)

Creates a new hard link between two files.

public static void CreateHardlink(string sourcePath, string targetPath)

Parameters

sourcePath string

The path of the link to create.

targetPath string

The absolute path of the existing file to point to.

Exceptions

IOException

Creating the hard link failed.

UnauthorizedAccessException

You have insufficient rights to create the hard link.

PlatformNotSupportedException

This method is called on a system with no hard link support.

CreateSymlink(string, string)

Creates a new symbolic link to a file or directory.

public static void CreateSymlink(string sourcePath, string targetPath)

Parameters

sourcePath string

The path of the link to create.

targetPath string

The path of the existing file or directory to point to (relative to sourcePath).

Exceptions

IOException

Creating the symbolic link failed.

UnauthorizedAccessException

You have insufficient rights to create the symbolic link.

PlatformNotSupportedException

This method is called on a system with no symbolic link support.

DetermineTimeAccuracy(string)

Determines the accuracy with which the filesystem underlying a specific directory can store file-changed times.

public static int DetermineTimeAccuracy(string path)

Parameters

path string

The path of the directory to check.

Returns

int

The accuracy in number of seconds. (i.e. 0 = perfect, 1 = may be off by up to one second)

Exceptions

DirectoryNotFoundException

The specified directory doesn't exist.

IOException

Writing to the directory fails.

UnauthorizedAccessException

You have insufficient rights to write to the directory.

DisableWriteProtection(string)

Removes whatever means the current platform provides to prevent write access to a directory (read-only attribute, ACLs, Unix octals, etc.).

public static void DisableWriteProtection(string path)

Parameters

path string

The directory to unprotect.

Remarks

May do nothing if the platform doesn't provide any known protection mechanisms.

Exceptions

IOException

There was a problem removing the write protection.

UnauthorizedAccessException

You have insufficient rights to remove the write protection.

EnableWriteProtection(string)

Uses the best means the current platform provides to prevent further write access to a directory (read-only attribute, ACLs, Unix octals, etc.).

public static void EnableWriteProtection(string path)

Parameters

path string

The directory to protect.

Remarks

May do nothing if the platform doesn't provide any known protection mechanisms.

Exceptions

IOException

There was a problem applying the write protection.

UnauthorizedAccessException

You have insufficient rights to apply the write protection.

ExistsCaseSensitive(string)

Like Exists(string) but case-sensitive, even on Windows.

public static bool ExistsCaseSensitive(string path)

Parameters

path string

Returns

bool

GetFileID(FileInfo)

Returns the file ID (on Windows) or Inode (on Unix) of a file.

public static long GetFileID(this FileInfo file)

Parameters

file FileInfo

The file.

Returns

long

Exceptions

IOException

There was an IO problem checking the files.

UnauthorizedAccessException

You have insufficient rights to check the files.

GetFileID(string)

Returns the file ID (on Windows) or Inode (on Unix) of a file.

public static long GetFileID(string path)

Parameters

path string

The path of the file.

Returns

long

Exceptions

IOException

There was an IO problem checking the file.

UnauthorizedAccessException

You have insufficient rights to check the files.

GetFilesRecursive(string, bool)

Returns the full paths of all files in a directory and its subdirectories.

public static IList<string> GetFilesRecursive(string path, bool followDirSymlinks = false)

Parameters

path string

The path of the directory to search for files.

followDirSymlinks bool

If true recurse into directory symlinks.

Returns

IList<string>

IsBreakoutPath(string?)

Determines whether a path might escape its parent directory (by being absolute or using ..).

[Pure]
public static bool IsBreakoutPath(string? path)

Parameters

path string

Returns

bool

IsExecutable(string)

Checks whether a file is marked as Unix-executable.

public static bool IsExecutable(string path)

Parameters

path string

Returns

bool

true if path points to an executable; false otherwise.

Remarks

Will return false for non-existing files. Will always return false on non-Unixoid systems.

Exceptions

UnauthorizedAccessException

You have insufficient rights to query the file's properties.

IsRegularFile(string)

Checks whether a file is a regular file (i.e. not a device file, symbolic link, etc.).

public static bool IsRegularFile(string path)

Parameters

path string

Returns

bool

true if path points to a regular file; false otherwise.

Remarks

Will return false for non-existing files.

Exceptions

UnauthorizedAccessException

You have insufficient rights to query the file's properties.

IsSymlink(FileSystemInfo, out string)

Checks whether a file is a Unix symbolic link.

public static bool IsSymlink(this FileSystemInfo item, out string target)

Parameters

item FileSystemInfo

The file to check.

target string

Returns the target the symbolic link points to if it exists.

Returns

bool

true if item points to a symbolic link; false otherwise.

Exceptions

IOException

There was an IO problem reading the file.

UnauthorizedAccessException

Read access to the file was denied.

IsSymlink(string)

Checks whether a file is a symbolic link.

public static bool IsSymlink(string path)

Parameters

path string

The path of the file to check.

Returns

bool

true if path points to a symbolic link; false otherwise.

Exceptions

IOException

There was an IO problem reading the file.

UnauthorizedAccessException

Read access to the file was denied.

IsSymlink(string, out string)

Checks whether a file is a symbolic link.

public static bool IsSymlink(string path, out string target)

Parameters

path string

The path of the file to check.

target string

Returns the target the symbolic link points to if it exists.

Returns

bool

true if path points to a symbolic link; false otherwise.

Exceptions

IOException

There was an IO problem reading the file.

UnauthorizedAccessException

Read access to the file was denied.

IsUnixFS(string)

Checks whether a directory is located on a filesystem with support for Unixoid features such as executable bits.

public static bool IsUnixFS(string path)

Parameters

path string

Returns

bool

true if path points to directory on a Unixoid filesystem; false otherwise.

Remarks

Will always return false on non-Unixoid systems. Only requires read access on Linux to determine file system. Requires write access on other Unixes (e.g. MacOS X).

Exceptions

DirectoryNotFoundException

The specified directory doesn't exist.

IOException

Checking the directory failed.

UnauthorizedAccessException

You have insufficient right to stat to the directory.

PathEquals(string?, string?)

Determines whether two file-system paths point to the same location.

[Pure]
public static bool PathEquals(string? path1, string? path2)

Parameters

path1 string

path2 string

Returns

bool

Remarks

Applies path normalization. Does not resolve symlinks. Case-insensitive on Windows and macOS.

ReadExtendedMetadata(string, string)

Reads metadata from an NTFS Alternate Data Stream (Windows) or extended file attribute (Unixoid).

public static byte[]? ReadExtendedMetadata(string path, string name)

Parameters

path string

The path of the file the Alternate Data Stream is associated with.

name string

The name of the metadata stream.

Returns

byte[]

The contents of the metadata stream; null if the file exists but the stream specified by name does not.

Exceptions

FileNotFoundException

The file specified by path does not exist.

IOException

There was a problem reading the metadata stream.

PlatformNotSupportedException

The current operating system provides no method for storing extended metadata.

ReadFirstLine(FileInfo, Encoding)

Reads the first line of text from a file.

public static string? ReadFirstLine(this FileInfo file, Encoding encoding)

Parameters

file FileInfo

The file to read from.

encoding Encoding

The text encoding to use for reading.

Returns

string

The first line of text in the file; null if decoding does not work on the contents.

Exceptions

IOException

A problem occurred while reading the file.

UnauthorizedAccessException

Read access to the file is not permitted.

RelativeTo(FileSystemInfo, FileSystemInfo)

Returns a relative path pointing to target from baseRef.

[Pure]
public static string RelativeTo(this FileSystemInfo target, FileSystemInfo baseRef)

Parameters

target FileSystemInfo

baseRef FileSystemInfo

Returns

string

Replace(string, string)

Replaces one file with another. Rolls back in case of problems. If the destination file does not exist yet, this acts like a simple rename.

public static void Replace(string sourcePath, string destinationPath)

Parameters

sourcePath string

The path of source directory.

destinationPath string

The path of the target directory. Must reside on the same filesystem as sourcePath.

Exceptions

ArgumentException

sourcePath and destinationPath are equal.

IOException

The file could not be replaced.

UnauthorizedAccessException

The read or write access to one of the files was denied.

ResetAcl(DirectoryInfo)

Removes any custom ACLs a user may have set, restores ACL inheritance and sets the Administrators group as the owner.

public static void ResetAcl(this DirectoryInfo directory)

Parameters

directory DirectoryInfo

SetExecutable(string, bool)

Marks a file as Unix-executable or not Unix-executable. Only works on Unixoid systems!

public static void SetExecutable(string path, bool executable)

Parameters

path string

The file to mark as executable or not executable.

executable bool

true to mark the file as executable, true to mark it as not executable.

Exceptions

FileNotFoundException

path points to a file that does not exist or cannot be accessed.

UnauthorizedAccessException

You have insufficient rights to change the file's properties.

PlatformNotSupportedException

This method is called on a non-Unixoid system.

ToNativePath(string?)

Replaces Unix-style directory slashes with DirectorySeparatorChar.

[Pure]
public static string? ToNativePath(this string? value)

Parameters

value string

Returns

string

ToUnixPath(string?)

Replaces DirectorySeparatorChar with Unix-style directory slashes.

[Pure]
public static string? ToUnixPath(this string? value)

Parameters

value string

Returns

string

Touch(string)

Sets the "last modified" timestamp for a file to now. Creates a new empty file if it does not exist yet.

public static void Touch(string path)

Parameters

path string

Exceptions

IOException

Creating the file or updating its timestamp failed.

UnauthorizedAccessException

You have insufficient rights to create the file or update its timestamp.

Walk(FileSystemInfo, Action<DirectoryInfo>?, Action<FileInfo>?, bool)

Walks a directory structure recursively and performs an action for every directory and file encountered.

public static void Walk(this FileSystemInfo element, Action<DirectoryInfo>? dirAction = null, Action<FileInfo>? fileAction = null, bool followDirSymlinks = false)

Parameters

element FileSystemInfo

The directory (or single file) to walk.

dirAction Action<DirectoryInfo>

The action to perform for every found directory (including the starting element); can be null.

fileAction Action<FileInfo>

The action to perform for every found file; can be null.

followDirSymlinks bool

If true recurse into directory symlinks; if false only execute dirAction for directory symlinks but do not recurse.

WalkThroughPrefix(DirectoryInfo)

Skips through any directories that only contain a single subdirectory and no files.

public static DirectoryInfo WalkThroughPrefix(this DirectoryInfo directory)

Parameters

directory DirectoryInfo

Returns

DirectoryInfo

Remarks

Ignores files that start with a dot.

WriteExtendedMetadata(string, string, byte[])

Writes metadata to an NTFS Alternate Data Stream (Windows) or extended file attribute (Unixoid).

public static void WriteExtendedMetadata(string path, string name, byte[] data)

Parameters

path string

The path of the file to associate the metadata with.

name string

The name of the metadata stream.

data byte[]

The data to write to the metadata stream.

Exceptions

FileNotFoundException

The file specified by path does not exist.

IOException

There was a problem writing the metadata stream.

UnauthorizedAccessException

You have insufficient rights to write the metadata.

PlatformNotSupportedException

The current operating system provides no method for storing extended metadata.