Class FileUtils

Provides filesystem-related helper methods.

Inheritance

Object

FileUtils

Namespace: NanoByte.Common.Storage

Assembly: NanoByte.Common.dll

Syntax

public static class FileUtils : Object

Methods

AreHardlinked(String, String)

Determines whether two files are hardlinked.

Declaration

public static bool AreHardlinked(string path1, string path2)

Parameters

Type	Name	Description
String	path1	The path of the first file.
String	path2	The path of the second file.

Returns

Type	Description
Boolean

Exceptions

Type	Condition
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).

Declaration

public static void CanonicalizeAcl(this ObjectSecurity objectSecurity)

Parameters

Type	Name	Description
ObjectSecurity	objectSecurity

Create(String, Int64)

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

Declaration

public static FileStream Create(string path, long expectedSize)

Parameters

Type	Name	Description
String	path	The path of the file.
Int64	expectedSize	The initial allocation size in bytes for the file.

Returns

Type	Description
FileStream	A stream for writing the file. No read access.

CreateHardlink(String, String)

Creates a new hard link between two files.

Declaration

public static void CreateHardlink(string sourcePath, string targetPath)

Parameters

Type	Name	Description
String	sourcePath	The path of the link to create.
String	targetPath	The absolute path of the existing file to point to.

Exceptions

Type	Condition
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.

Declaration

public static void CreateSymlink(string sourcePath, string targetPath)

Parameters

Type	Name	Description
String	sourcePath	The path of the link to create.
String	targetPath	The path of the existing file or directory to point to (relative to sourcePath).

Exceptions

Type	Condition
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.

Declaration

public static int DetermineTimeAccuracy(string path)

Parameters

Type	Name	Description
String	path	The path of the directory to check.

Returns

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

Exceptions

Type	Condition
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.).

Declaration

public static void DisableWriteProtection(string path)

Parameters

Type	Name	Description
String	path	The directory to unprotect.

Remarks

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

Exceptions

Type	Condition
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.).

Declaration

public static void EnableWriteProtection(string path)

Parameters

Type	Name	Description
String	path	The directory to protect.

Remarks

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

Exceptions

Type	Condition
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.

Declaration

public static bool ExistsCaseSensitive(string path)

Parameters

Type	Name	Description
String	path

Returns

Type	Description
Boolean

GetFileID(FileInfo)

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

Declaration

public static long GetFileID(this FileInfo file)

Parameters

Type	Name	Description
FileInfo	file	The file.

Returns

Type	Description
Int64

Exceptions

Type	Condition
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.

Declaration

public static long GetFileID(string path)

Parameters

Type	Name	Description
String	path	The path of the file.

Returns

Type	Description
Int64

Exceptions

Type	Condition
IOException	There was an IO problem checking the file.
UnauthorizedAccessException	You have insufficient rights to check the files.

GetFilesRecursive(String, Boolean)

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

Declaration

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

Parameters

Type	Name	Description
String	path	The path of the directory to search for files.
Boolean	followDirSymlinks	If true recurse into directory symlinks.

Returns

Type	Description
IList<String>

IsBreakoutPath(String)

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

Declaration

public static bool IsBreakoutPath(string path)

Parameters

Type	Name	Description
String	path

Returns

Type	Description
Boolean

IsExecutable(String)

Checks whether a file is marked as Unix-executable.

Declaration

public static bool IsExecutable(string path)

Parameters

Type	Name	Description
String	path

Returns

Type	Description
Boolean	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

Type	Condition
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.).

Declaration

public static bool IsRegularFile(string path)

Parameters

Type	Name	Description
String	path

Returns

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

Remarks

Will return false for non-existing files.

Exceptions

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

IsSymlink(FileSystemInfo, out String)

Checks whether a file is a Unix symbolic link.

Declaration

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

Parameters

Type	Name	Description
FileSystemInfo	item	The file to check.
String	target	Returns the target the symbolic link points to if it exists.

Returns

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

Exceptions

Type	Condition
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.

Declaration

public static bool IsSymlink(string path)

Parameters

Type	Name	Description
String	path	The path of the file to check.

Returns

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

Exceptions

Type	Condition
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.

Declaration

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

Parameters

Type	Name	Description
String	path	The path of the file to check.
String	target	Returns the target the symbolic link points to if it exists.

Returns

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

Exceptions

Type	Condition
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.

Declaration

public static bool IsUnixFS(string path)

Parameters

Type	Name	Description
String	path

Returns

Type	Description
Boolean	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

Type	Condition
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.

Declaration

public static bool PathEquals(string path1, string path2)

Parameters

Type	Name	Description
String	path1
String	path2

Returns

Type	Description
Boolean

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).

Declaration

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

Parameters

Type	Name	Description
String	path	The path of the file the Alternate Data Stream is associated with.
String	name	The name of the metadata stream.

Returns

Type	Description
Byte[]	The contents of the metadata stream; null if the file exists but the stream specified by name does not.

Exceptions

Type	Condition
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.

Declaration

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

Parameters

Type	Name	Description
FileInfo	file	The file to read from.
Encoding	encoding	The text encoding to use for reading.

Returns

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

Exceptions

Type	Condition
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.

Declaration

public static string RelativeTo(this FileSystemInfo target, FileSystemInfo baseRef)

Parameters

Type	Name	Description
FileSystemInfo	target
FileSystemInfo	baseRef

Returns

Type	Description
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.

Declaration

public static void Replace(string sourcePath, string destinationPath)

Parameters

Type	Name	Description
String	sourcePath	The path of source directory.
String	destinationPath	The path of the target directory. Must reside on the same filesystem as sourcePath.

Exceptions

Type	Condition
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.

Declaration

public static void ResetAcl(this DirectoryInfo directory)

Parameters

Type	Name	Description
DirectoryInfo	directory

SetExecutable(String, Boolean)

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

Declaration

public static void SetExecutable(string path, bool executable)

Parameters

Type	Name	Description
String	path	The file to mark as executable or not executable.
Boolean	executable	true to mark the file as executable, true to mark it as not executable.

Exceptions

Type	Condition
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.

Declaration

public static string ToNativePath(this string value)

Parameters

Type	Name	Description
String	value

Returns

Type	Description
String

Touch(String)

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

Declaration

public static void Touch(string path)

Parameters

Type	Name	Description
String	path

Exceptions

Type	Condition
IOException	Creating the file or updating its timestamp failed.
UnauthorizedAccessException	You have insufficient rights to create the file or update its timestamp.

ToUnixPath(String)

Replaces DirectorySeparatorChar with Unix-style directory slashes.

Declaration

public static string ToUnixPath(this string value)

Parameters

Type	Name	Description
String	value

Returns

Type	Description
String

Walk(FileSystemInfo, Action<DirectoryInfo>, Action<FileInfo>, Boolean)

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

Declaration

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

Parameters

Type	Name	Description
FileSystemInfo	element	The directory (or single file) to walk.
Action<DirectoryInfo>	dirAction	The action to perform for every found directory (including the starting element); can be null.
Action<FileInfo>	fileAction	The action to perform for every found file; can be null.
Boolean	followDirSymlinks	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.

Declaration

public static DirectoryInfo WalkThroughPrefix(this DirectoryInfo directory)

Parameters

Type	Name	Description
DirectoryInfo	directory

Returns

Type	Description
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).

Declaration

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

Parameters

Type	Name	Description
String	path	The path of the file to associate the metadata with.
String	name	The name of the metadata stream.
Byte[]	data	The data to write to the metadata stream.

Exceptions

Type	Condition
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.