Class FileUtils
Provides filesystem-related helper methods.
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 |
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 |
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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; |
Exceptions
Type | Condition |
---|---|
FileNotFoundException | The file specified by |
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; |
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 |
Exceptions
Type | Condition |
---|---|
ArgumentException |
|
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 |
|
Exceptions
Type | Condition |
---|---|
FileNotFoundException |
|
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 |
Action<FileInfo> | fileAction | The action to perform for every found file; can be |
Boolean | followDirSymlinks | If |
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 |
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. |