IFileSystem#

Fully qualified name: carb::filesystem::IFileSystem

Defined in carb/filesystem/detail/IFileSystem2.h

struct IFileSystem#

The Carbonite FileSystem interface.

Allows accessing low- and mid-level file operations in a platform-independent fashion. All paths are expected to be UTF-8 encoded and using forward slash as a path separator (though backslash is allowed on Windows).

On Windows, the maximum path length of 32,767 characters is supported, however each path component may not exceed 255 characters.

Linux has a maximum filename length of 255 characters for most filesystems (including ext4), and a maximum path size of 4,096 characters.

Public Functions

virtual cpp::zstring_view getExecutablePath() const noexcept = 0#

Returns the full path to the binary for this process.

Returns:

The full canonical path to the binary that started this process, including executable name and extension. This references static memory and will not change for the lifetime of the process.

virtual cpp::zstring_view getExecutableDirectoryPath(
) const noexcept = 0#

Returns the full path to the directory that contains the binary for this process.

Returns:

The full canonical directory path that contains the binary that started this process. This does not include the binary file name. This references static memory and will not change for the lifetime of this process. Does not include the trailing path separator.

virtual omni::expected<void, ErrorCode> setAppDirectoryPath(
cpp::string_view path,
) noexcept = 0#

Sets the full path to the ‘app’ directory.

This is effectively just a directory that is stored by this interface and accessible through getAppDirectoryPath. On Windows, any extended path prefix (\\?\ is removed) and backslashes are converted to forward slashes.

Thread Safety

Thread safe with respect to other calls to this function and getAppDirectoryPath, though a race may occur if another thread is attempting to set the app directory or other threads are attempting to read it.

Possible Error values

Parameters:

path – The path to save as the ‘app’ directory.

Returns:

void on success, or a carb::ErrorCode describing the failure.

virtual omni::string getAppDirectoryPath() const noexcept = 0#

Retrieves the stored ‘app’ directory.

This is effectively just a directory that is stored by this interface (setAppDirectoryPath).

Thread Safety

This call is thread-safe with respect to setAppDirectoryPath, though a race may occur if another thread is attempting to set the app directory while this thread is reading it.

Returns:

The stored ‘app’ directory.

virtual omni::expected<void, ErrorCode> setWorkingDirectory(
cpp::string_view path,
) const noexcept = 0#

Sets the working directory for the process.

See also

getWorkingDirectory

Warning

This is a process-wide value, and setting/getting it is not thread-safe.

Parameters:

path – The new working directory path. May be relative or absolute, but must exist. Must be a directory.

Returns:

void on success, or a carb::ErrorCode describing the failure.

virtual omni::expected<omni::string, ErrorCode> getWorkingDirectory(
) const noexcept = 0#

Returns the current working directory.

See also

setWorkingDirectory

Warning

This is a process-wide value, and setting/getting it is not thread-safe.

Returns:

The current working directory.

virtual omni::expected<bool, ErrorCode> checkExists(
cpp::string_view path,
) const noexcept = 0#

Checks for the existence of a path.

Warning

expected<bool, E> is error-prone as comparisons may not be testing what is intended. Be explicit.

Parameters:

path – The path to text for existence. May be absolute or relative to the current working directory (getWorkingDirectory).

Returns:

true if path exists, false if path does not exist; otherwise a carb::ErrorCode indicating an error resulting from checking for the file existence.

inline bool exists(cpp::string_view path) const noexcept#

Simply checks for the existence of a path.

See also

checkExists

Parameters:

path – The path to text for existence. May be absolute or relative to the current working directory (getWorkingDirectory).

Returns:

true if path exists; false otherwise. No error information is provided. If additional error information is required, use checkExists.

virtual omni::expected<bool, ErrorCode> checkWritable(
cpp::string_view path,
) const noexcept = 0#

Checks whether a path is writable.

Errors

May be one of the following:

  • carb::ErrorCode NotFound - The path was not found

  • carb::ErrorCode NotDirectory - Parent path is not a directory so path can not be created

  • carb::ErrorCode AccessDenied - Access was denied to the file (no permission to access)

  • Other errors may be reported based on the underlying platform calls

Note

This accessibility check only answers the question of whether the user has permission to write to the file, not that an open for write will always succeed. At least on Windows, it is still possible that another thread or process could have the file open without write sharing capabilities. In this case, the caller should just do a test open of the file since that will answer the question of whether write sharing is currently allowed on the file. On Linux there isn’t any kernel enforced file sharing functionality so permission to the file should also imply the user will succeed to open it for write.

Warning

expected<bool, E> is error-prone as comparisons may not be testing what is intended. Be explicit.

Parameters:

path – The path to test for writability. May be absolute or relative to the current working directory (getWorkingDirectory).

Returns:

true if path exists and is writable, false if path exists but is not writable; otherwise a carb::ErrorCode that gives more information about the failure.

inline bool isWritable(cpp::string_view path) const noexcept#

Simply checks whether a path is writable.

See also

checkWritable

Note

This accessibility check only answers the question of whether the user has permission to write to the file, not that an open for write will always succeed. At least on Windows, it is still possible that another thread or process could have the file open without write sharing capabilities. In this case, the caller should just do a test open of the file since that will answer the question of whether write sharing is currently allowed on the file. On Linux there isn’t any kernel enforced file sharing functionality so permission to the file should also imply the user will succeed to open it for write.

Parameters:

path – The path to test for writability. May be absolute or relative to the current working directory (getWorkingDirectory).

Returns:

true if path is an existing writable file path, or false otherwise. No error information is provided. If additional error information is required, use checkWritable.

virtual omni::expected<bool, ErrorCode> checkReadable(
cpp::string_view path,
) const noexcept = 0#

Checks whether a path is readable.

Errors

May be one of the following:

  • carb::ErrorCode NotFound - The path was not found

  • carb::ErrorCode NotDirectory - Parent path is not a directory so path can not be created

  • carb::ErrorCode AccessDenied - Access was denied to the file (no permission to access)

  • Other errors may be reported based on the underlying platform calls

Note

This accessibility check only answers the question of whether the user has permission to read the file, not that an open for read will always succeed. At least on Windows, it is still possible that another thread or process could have the file open without read sharing capabilities. In this case, the caller should just do a test open of the file since that will answer the question of whether read sharing is currently allowed on the file. On Linux there isn’t any kernel enforced file sharing functionality so permission to the file should also imply the user will succeed to open it for read.

Warning

expected<bool, E> is error-prone as comparisons may not be testing what is intended. Be explicit.

Parameters:

path – The path to test for readability. May be absolute or relative to the current working directory (getWorkingDirectory).

Returns:

true if path exists and is readable, false if path exists but is not readable; otherwise a carb::ErrorCode that gives more information about the failure.

inline bool isReadable(cpp::string_view path) const noexcept#

Simply checks whether a path is readable.

See also

checkReadable

Note

This accessibility check only answers the question of whether the user has permission to read the file, not that an open for read will always succeed. At least on Windows, it is still possible that another thread or process could have the file open without read sharing capabilities. In this case, the caller should just do a test open of the file since that will answer the question of whether read sharing is currently allowed on the file. On Linux there isn’t any kernel enforced file sharing functionality so permission to the file should also imply the user will succeed to open it for read.

Parameters:

path – The path to test for readability. May be absolute or relative to the current working directory (getWorkingDirectory).

Returns:

true if path is an existing readable file path, or false otherwise. No error information is provided. If additional error information is required, use checkReadable.

virtual omni::expected<bool, ErrorCode> checkDirectory(
cpp::string_view path,
) const noexcept = 0#

Checks whether a path is a directory.

Possible Error values

May be one of the following:

  • carb::ErrorCode NotFound - The path was not found

  • Other errors may be reported based on the underlying platform calls

Warning

expected<bool, E> is error-prone as comparisons may not be testing what is intended. Be explicit.

Parameters:

path – The path to test as a directory. May be absolute or relative to the current working directory (getWorkingDirectory).

Returns:

true if path exists and is a directory, false if path exists but is not a directory; or a carb::ErrorCode value indicating the error.

inline bool isDirectory(cpp::string_view path) const noexcept#

Simply checks whether a path is a directory.

See also

checkDirectory

Parameters:

path – The path to test as a directory. May be absolute or relative to the current working directory (getWorkingDirectory).

Returns:

true if path exists and is a directory; false otherwise. No error information is provided. If additional error information is required, use checkDirectory.

virtual omni::expected<omni::string, ErrorCode> makeCanonicalPath(
cpp::string_view path,
bool mustExist = true,
) const noexcept = 0#

Use system functions to build a canonical path relative to a base directory (or the working directory).

Errors

May be one of the following:

  • carb::ErrorCode NotFound - The path was not found

  • Other errors may be reported based on the underlying platform calls

Parameters:

  • path – Path to canonicalize. May be absolute or relative to the current working directory (getWorkingDirectory).

  • mustExist – If true, the path must exist; otherwise a canonical path is computed regardless of whether it exists (Windows only; note that the computed path may be a different case).

Returns:

The canonical path string, or a carb::ErrorCode if an error occurs.

virtual omni::expected<omni::string, ErrorCode> makeCanonicalPath(
cpp::string_view path,
cpp::string_view base,
bool mustExist = true,
) const noexcept = 0#

Use system functions to build a canonical path relative to a base directory (or the working directory).

Errors

May be one of the following:

  • carb::ErrorCode NotFound - The path was not found

  • Other errors may be reported based on the underlying platform calls

Parameters:

  • path – A path to canonicalize that is relative to base.

  • base – The directory that is used as a relative base for path instead of the current working directory.

  • mustExist – If true, the path must exist; otherwise a canonical path is computed regardless of whether it exists (Windows only; note that the computed path may be a different case).

Returns:

The canonical path string, or a carb::ErrorCode if an error occurs.

inline omni::expected<ScopedFile, ErrorCode> open(
cpp::string_view path,
OpenMode mode,
bool binary,
) const noexcept#

Opens a file for operations based on the given mode.

The returned file object can be used to access the file. Allowing the ScopedFile to go out of scope or explicitly calling File::close() will close the file.

Possible Errors

Parameters:

  • path – The file path to open. May be absolute or relative to the current working directory (see getWorkingDirectory).

  • mode – The OpenMode to open the file as.

  • binary – Whether the file should be opened as binary or not. Binary has no affect on POSIX where the line ending is always \n. On Windows a value of false means that line endings of "\r\n" will be converted to just \n on read, and vice versa on write; a value of true means that line endings are not converted.

Returns:

A ScopedFile representing the open file if successful. If a failure occurs, a carb::ErrorCode is returned instead indicating the error.

virtual omni::expected<FileTime, ErrorCode> getModTime(
cpp::string_view path,
) const noexcept = 0#

Gets the time of last modification to the file.

Errors

  • carb::ErrorCode NotFound - The file was not found

  • Other errors may be reported based on the underlying platform calls

Parameters:

path – The path to query. May be absolute or relative to the current working directory (see getWorkingDirectory).

Returns:

A FileTime indicating the time this file was last modified if successful, or an carb::ErrorCode if an error occurs.

virtual omni::expected<FileTime, ErrorCode> getCreateTime(
cpp::string_view path,
) const noexcept = 0#

Gets the time of file creation.

Errors

  • carb::ErrorCode NotFound - The file was not found

  • Other errors may be reported based on the underlying platform calls

Parameters:

path – The path to query. May be absolute or relative to the current working directory (see getWorkingDirectory).

Returns:

A FileTime indicating the time this file was last modified if successful, or an carb::ErrorCode if an error occurs.

virtual FileTime getCurrentTime() const noexcept = 0#

Returns the current high-resolution time of the filesystem.

Returns:

A FileTime indicating the current time of the filesystem.

virtual omni::expected<void, ErrorCode> removeFile(
cpp::string_view path,
) const noexcept = 0#

Removes (deletes) a file.

Errors

  • carb::ErrorCode NotFound - The file was not found

  • Other errors may be reported based on the underlying platform calls

Parameters:

path – The path of the file to be removed. May be absolute or relative to the current working directory (see getWorkingDirectory).

Returns:

void if the remove operation succeeded; or a carb::ErrorCode if an error occurred.

virtual omni::expected<void, ErrorCode> removeDirectory(
cpp::string_view path,
) const noexcept = 0#

Removes a directory along with all files and subdirectories.

Errors

  • carb::ErrorCode NotFound - The path was not found

  • carb::ErrorCode NotDirectory - Path was not a directory

  • Other errors may be reported based on the underlying platform calls

Note

Does not follow symbolic links; the links themselves will be removed but targets will not.

Warning

It is not recommended to delete the current working directory as this will leave the application in an undefined state.

Parameters:

path – The path of the directory to remove. May be absolute or relative to the current working directory (see getWorkingDirectory).

Returns:

void if the remove operation succeeded; or a carb::ErrorCode if an error occurred.

virtual omni::expected<omni::string, ErrorCode> makeTempDirectory(
) const noexcept = 0#

Creates a temporary directory.

The directory is created under the system temporary directory area and will have a randomized, unique name.

Returns:

The absolute path of the temporary directory (without a trailing path separator) if successful; otherwise returns an error code indicating why the directory creation was unsuccessful.

virtual omni::expected<CreateType, ErrorCode> makeSingleDirectory(
cpp::string_view path,
) const noexcept = 0#

Creates a single directory.

All parent directories must already exist.

Results

  • carb::ErrorCode AlreadyExists - Path already exists as a file, preventing creation.

  • Other errors may be reported based on the underlying platform calls

Parameters:

path – The directory path to create. May be absolute or relative to the current working directory (see getWorkingDirectory). If any parent directories do not exist, the creation will fail.

Returns:

A CreateType indicating successful creation (or existence), or a carb::ErrorCode value describing the outcome of the request.

virtual omni::expected<CreateType, ErrorCode> makeDirectories(
cpp::string_view path,
) const noexcept = 0#

Creates a directory, including any non-existing parent directories.

All path components listed will be created if they do not exist. If any exist already as a non-directory, the operation will fail. If an attempt to create any of the directories fails then the entire operation will fail. A failed operation will not clean up any directories that were successfully created.

Results

  • carb::ErrorCode AlreadyExists - Path already exists as a file, preventing creation.

  • Other errors may be reported based on the underlying platform calls

Parameters:

path – The path to the directory to create. May be absolute or relative to the current working directory (see getWorkingDirectory).

Returns:

A CreateType indicating successful creation (or existence), or a carb::ErrorCode value describing the outcome of the request.

virtual omni::expected<void, ErrorCode> copyFile(
cpp::string_view from,
cpp::string_view to,
) const noexcept = 0#

Copies a file.

The file is not copied if the destination file already exists. API calls are CopyFileW on Windows, sendfile on Linux, falling back to read/write on POSIX. Destination directories are not created by this function.

Results

  • carb::ErrorCode NotFound - The file was not found

  • carb::ErrorCode AlreadyExists - The target file already exists

  • Other errors may be reported based on the underlying platform calls

Parameters:

  • from – The file path to copy from. May be absolute or relative to the current working directory (see getWorkingDirectory).

  • to – The destination file path. May be absolute or relative to the current working directory (see getWorkingDirectory).

Returns:

void if the request succeeded, or a carb::ErrorCode value describing the error.

virtual omni::expected<void, ErrorCode> movePath(
cpp::string_view from,
cpp::string_view to,
) const noexcept = 0#

Moves (or renames) a file or directory.

The path is not moved if the destination already exists. API calls are MoveFileW on Windows, or rename on POSIX.

Results

  • carb::ErrorCode NotFound - The file was not found

  • carb::ErrorCode AlreadyExists - The target file already exists

  • Other errors may be reported based on the underlying platform calls

Parameters:

  • from – The file path that will be renamed. May be absolute or relative to the current working directory (see getWorkingDirectory).

  • to – The destination path. May be absolute or relative to the current working directory (see getWorkingDirectory).

Returns:

void if the request succeeded, or a carb::ErrorCode value describing the error.

Post:

Upon success, from no longer exists and to exists instead referencing the same file that from did previously.

template<typename Pred>
omni::expected<void, ErrorCode> forEachDirectoryItem(
cpp::string_view path,
bool recurse,
Pred &&pred,
) const#

Iterates through each item in a directory, optionally recursing into subdirectories.

Results

  • carb::ErrorCode NotFound - The path was not found

  • Other errors may be reported based on the underlying platform calls

Warning

Another thread or process could modify items, so the information passed to pred may be out-of-date.

Parameters:

  • path – The path to the root directory to iterate. May be absolute or relative to the current working directory (see getWorkingDirectory).

  • recurse – Whether to recurse into subdirectories. If true, symbolic links will be followed and iteration will proceed into a subdirectory before continuing at the current level.

  • pred – The predicate called with a reference to DirectoryItemInfo for each encountered item. The return value may be either WalkAction or void (which acts like WalkAction::eContinue).

Returns:

void if the iteration succeeded, or a carb::ErrorCode value describing the error.

virtual omni::expected<SubscriptionId, ErrorCode> subscribeToChangeEvents(
cpp::string_view path,
omni::move_only_function<void(cpp::zstring_view, ChangeAction, cpp::zstring_view)> func,
) const noexcept = 0#

Subscribes to listening for change events for a given path.

Implemented with INotify on Linux (inotify_init1) and ReadDirectoryChangesW on Windows.

See also

unsubscribeFromChangeEvents

Results

  • carb::ErrorCode Fail - A system error occurred

  • Other errors may be reported based on the underlying platform calls

Note

Subscriptions are not recursive. Subscribing to a directory will only monitor that directory for changes, not any subdirectories. Though depending on the System, some changes to subdirectories may trigger a ChangeAction::eModified change event.

Note

If path is a directory, deleting the directory will produce a final ChangeAction::eDeleted event but no more events will be received for that subscription, even if a directory with the same name is created again.

Note

If path is a file, deleting the file and re-creating it will still receive change events.

Warning

The System may have limits to the number of subscriptions that can be simultaneously created. Linux has a configurable limit in /proc/sys/fs/inotify/max_user_watches.

Parameters:

  • path – The path to listen to. Must be an existing file or directory. May be absolute or relative to the current working directory (see getWorkingDirectory).

  • func – The function to call when change events are noticed. This function will be called potentially multiple times from a background monitoring thread, but will not be called in parallel. It is safe to call unsubscribeFromChangeEvents from within this function.

Returns:

A subscription ID if the path was successfully subscribed; otherwise an error result is returned.

virtual omni::expected<void, ErrorCode> unsubscribeFromChangeEvents(
SubscriptionId id,
) const noexcept = 0#

Unsubscribes from listening to change events.

Results

  • carb::ErrorCode Fail - A system error occurred

  • carb::ErrorCode NotFound - The given id was not a valid and current subscription ID

  • Other errors may be reported based on the underlying platform calls

Note

It is safe to call this from within the callback provided to subscribeToChangeEvents(). This function will not return until the subscription callback is guaranteed to have exited by all threads (except a thread calling this function from within the callback).

Parameters:

id – The subscription ID previously created with subscribeToChangeEvents().

Returns:

void if the request succeeded, otherwise a carb::ErrorCode value describing the error.

virtual omni::expected<void, ErrorCode> getFileInfo(
cpp::string_view path,
FileInfo &out,
) const noexcept = 0#

Fills a FileInfo struct with information about a given path.

Results

  • carb::ErrorCode NotFound - The file was not found

  • carb::ErrorCode AccessDenied - Access was denied to the file

  • Other errors may be reported based on the underlying platform calls

Parameters:

  • path – The path to the file or directory. May be absolute or relative to the current working directory (see getWorkingDirectory).

  • out – [out] receives information about the file if void is returned; otherwise this struct is in a valid but undefined state.

Returns:

void if the request succeeded, otherwise a carb::ErrorCode value describing the error.

Public Static Functions

static inline constexpr carb::InterfaceDesc getInterfaceDesc(
) noexcept#

Returns information about this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns:

The carb::InterfaceDesc struct with information about this interface.

static inline constexpr carb::InterfaceDesc getLatestInterfaceDesc(
) noexcept#

Returns information about the latest version of this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns:

The carb::InterfaceDesc struct with information about the latest version of this interface.