carb::filesystem::IFileSystem

Defined in carb/filesystem/IFileSystem.h

struct IFileSystem

Defines a file system for Carbonite.

This interface provides a number of useful platform independent functions when working with files and folders in a file system. All paths are in UTF-8 encoding using forward slash as path separator.

On Windows, the maximum path of 32767 characters is supported. However, path components can’t be longer than 255 characters. Linux has a maximum filename length of 255 characters for most filesystems (including EXT4), and a maximum path of 4096 characters.

Public Types

typedef WalkAction (*OnDirectoryItemFn)(const DirectoryItemInfo *const info, void *userData)

User implemented callback function type for directory iteration.

Note

On Posix systems, a block device, socket, or pipe will still have info->type as DirectoryItemType::eFile, but ErrorApi::getError() will report omni::core::kResultInvalidDataType; otherwise ErrorApi::getError() will report omni::core::kResultSuccess.

Note

It is entirely possible that by the time this callback function is called for a given file or directory, that file or directory could have already been deleted, moved, or renamed by another thread or process. In this case the file information that is passed to the callback function may already be out of date. The callback function should take this into account before taking any action on the given file or directory. One possible way to detect this is to check if the info->createdTimestamp and info->modifiedTimestamp values are zero. The callback could also verify that the file still exists before acting on it.

Param info: about a file. See DirectoryItemInfo. The path member will be prefixed by the path passed to forEachDirectoryItem() (or forEachDirectoryItemRecursive())
Param userData: Any data that needs to be passed to the function for managing state across function calls, etc.
Return: one of the WalkAction enum values to instruct forEachDirectoryItem[Recursive] on how to proceed.

Public Functions

inline std::string makeCanonicalPath(const char *path, const char *base = nullptr, CanonicalFlags flags = fCanonicalFlagCheckExists)

Use platform functions to build canonical path relative to the base root.

The path must exist if fCanonicalFlagCheckExists is passed in the flags parameter.

Errors

Accessible via carb::ErrorApi. This function always modifies the error state.

omni::core::kResultSuccess - No error occurred
omni::core::kResultInvalidArgument - path was nullptr
omni::core::kResultNotFound - The file was not found
Other errors may be reported based on the underlying platform calls

Note

By default, this assumes that the requested file exists on the filesystem. On Linux, the existence of the file will still be checked as a side effect of the operation. On Windows however, no explicit check for the file existing in the filesystem will be performed unless the fCanonicalFlagCheckExists flag is used.

Parameters

path – The absolute or relative path to canonicalize.
base – The base path to resolve relative path against. This can be nullptrto use the working directory (as returned from getCurrentDirectoryPath()) to resolve the relative path.
flags – Flags to control the behavior of this operation.

Returns

A std::string containing the canonicalized path, or an empty string if an error occurs.

inline bool setFilePositionBegin(File *file)

helper functions to move to the beginning of an open file.

See also

setFilePosition()

Errors

Accessible via carb::ErrorApi

Note: Error state is not changed unless false is returned
Other errors may be reported based on the underlying platform calls

Parameters: file – [in] the file stream
Returns: true if the file pointer is successfully moved; false if an error occurs.

Public Members

const char *(*getExecutablePath)()

Returns the full path to the executable for this program.

ErrorApi state is not changed by this function.

Return: the full canonical path to the executable, including executable name and extension. This path will not change for the lifetime of the process.

const char *(*getExecutableDirectoryPath)()

Returns the full path to the directory that contains the executable for this program.

ErrorApi state is not changed by this function.

Return: the full canonical path to the directory that contains the executable file. This will not include the executable filename itself. This path will not change for the lifetime of the process.

const char *(*getAppDirectoryPath)()

Retrieves the full path to the ‘app’.

ErrorApi state is not changed by this function.

Note

Access to the application directory string is not thread safe. It is the caller’s responsibility to ensure the application path is not being modified from another thread while it is being retrieved.

Return: the buffer containing the application path string. The contents of this buffer will be modified by any call to setAppDirectoryPath(). The buffer itself will persist for the lifetime of the framework. This will return nullptr until it is initialized by a call to setAppDirectoryPath().

void (*setAppDirectoryPath)(const char *path)

Sets the full path to the ‘app’.

Errors

Accessible via carb::ErrorApi

omni::core::kResultSuccess - No error occurred
omni::core::kResultOutOfMemory - A buffer to store the path could not be allocated
omni::core::kResultInsufficientBuffer - path exceeds the size of the buffer

Note

(Windows) The extended path prefix is stripped if provided. Directory separators are converted to /.

Param path: [in] the relative or absolute path to the ‘app’. If a relative path is used, this will be resolved relative to the current working directory.
Return: no return value.

const char *(*getCurrentDirectoryPath)()

Returns the full path to the current working directory.

Errors

Accessible via carb::ErrorApi

Note: Error state is not changed on success
omni::core::kResultOutOfMemory - A buffer to store the path could not be allocated
omni::core::kResultInsufficientBuffer - the working directory exceeds the size of the buffer
Other errors may be reported based on the underlying platform calls

Note

Retrieving the current working directory is not thread safe. Since only a single working directory is maintained for each process, it could be getting changed from another thread while being retrieved. It is the caller’s responsibility to ensure that all access to the current working directory is safely serialized.

Return: nullptr if an error occurs, or the buffer containing the current working directory path string. The contents of this buffer will be modified by any call to getCurrentDirectoryPath() or setCurrentDirectoryPath(). The buffer itself will persist for the lifetime of the framework.

bool (*setCurrentDirectoryPath)(const char *path)

Sets the current working directory for the system.

Errors

Accessible via carb::ErrorApi

Note: Error state is not changed on success
omni::core::kResultInvalidArgument - path was nullptr
omni::core::kResultOutOfMemory - A buffer to store the path could not be allocated
omni::core::kResultInsufficientBuffer - the working directory exceeds the size of the buffer
Other errors may be reported based on the underlying platform calls

Note

Setting or retrieving the current working directory is not thread safe. Since the current working directory is global to the process, the caller is responsible for guaranteeing that the working directory will not change while attempting to retrieve it.

Param path: [in] the new current working directory path. This may be a relative or absolute path. This must name a directory that already exists. This name must not exist as a file on the file system. This may not be nullptr.
Return: true if the new working directory is successfully set; false if an error occurs.

bool (*exists)(const char *path)

Tests whether the path provided exists in the file system.

This function does not generate any error logging.

Errors

Accessible via carb::ErrorApi

Note: Error state is not changed on success
omni::core::kResultInvalidArgument - path was nullptr
omni::core::kResultNotFound - The file was not found
Other errors may be reported based on the underlying platform calls

Param path: The absolute or relative path to test for existence. Relative paths are resolved from the current working directory (as returned from getCurrentDirectoryPath()).
Return: true if and only if ‘path’ exists in the file system.

bool (*isWritable)(const char *path)

Tests whether it’s possible to write to file with the provided path.

Errors

Accessible via carb::ErrorApi

Note: Error state is not changed unless false is returned
omni::core::kResultSuccess - path exists but was not writable
omni::core::kResultInvalidArgument - path is nullptr
omni::core::kResultNotFound - The file was not found
omni::core::kResultInvalidState - Parent path is not a directory so path can not be created
omni::core::kResultAccessDenied - Access was denied to the file
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.

Param path: The absolute or relative path to test for writability. Relative paths are resolved from the current working directory (as returned from getCurrentDirectoryPath()).
Return: true if it’s possible to write to this file.

bool (*isDirectory)(const char *path)

Tests whether the path provided is a directory.

Errors

Accessible via carb::ErrorApi

Note: Error state is not changed unless false is returned
omni::core::kResultSuccess - path exists but was not a directory
omni::core::kResultInvalidArgument - path is nullptr
omni::core::kResultNotFound - The file was not found
Other errors may be reported based on the underlying platform calls

Param path: The absolute or relative path to test for existence. Relative paths are resolved from the current working directory (as returned from getCurrentDirectoryPath()).
Return: true if and only if ‘path’ is a directory.

size_t (*makeCanonicalPathEx)(const char *path, const char *base, char *buffer, size_t bufferSize)

Use platform functions to build canonical path relative to the base root.

The path must exist. See makeCanonicalPath() or makeCanonicalPathEx2() for a version where the path may not need to exist.

Errors

Accessible via carb::ErrorApi. This function always modifies the error state.

omni::core::kResultSuccess - No error occurred
omni::core::kResultInvalidArgument - path was nullptr
omni::core::kResultNotFound - The file was not found
omni::core::kResultInsufficientBuffer - The provided buffer was too small to receive the canonicalized string. The contents of buffer are unchanged and the return value is the number of bytes required (including the NUL terminator).
omni::core::kResultNullPointer - No buffer was provided, so nothing was written. The return value is the number of bytes required to contain the canonical path (include the NUL terminator).
Other errors may be reported based on the underlying platform calls

Param path: The absolute or relative path to canonicalize.
Param base: The base path to resolve relative path against. This can be nullptrto use the working directory (as returned from getCurrentDirectoryPath()) to resolve the relative path.
Param buffer: The buffer to write the canonical path to. This may be nullptr if only the required size of the buffer is needed.
Param bufferSize: The size of the buffer buffer in bytes.
Return: The number of characters written to the buffer buffer if the buffer is large enough. If the buffer is not large enough, nothing will be written to the buffer and the required size of the buffer in bytes including the NUL terminator will be returned. If an error occurs, 0 is returned.

File *(*openFileToRead)(const char *path)

Opens a file for reading in binary mode.

Remark

This opens an existing file for reading. If the file does not exist, this will fail. A new file will never be created if the named file does not already exist. If a new file needs to be created, it must first be opened for write with openFileToWrite(), for read and write with openFileToReadWrite(), or for append with openFileToAppend(). The file pointer will initially be at the beginning of the file. All reads will occur starting from the current file pointer position.

Errors

Accessible via carb::ErrorApi

Note: Error state is not changed with a non-nullptr return value
omni::core::kResultInvalidArgument - path was nullptr
omni::core::kResultNotFound - The file was not found
omni::core::kResultAccessDenied - Access was denied to the file
omni::core::kResultOutOfMemory - Allocation failure
Other errors may be reported based on the underlying platform calls

Param path: [in] The absolute or relative path for the file. This may not be nullptr. Relative paths are resolved from the current working directory (as returned from getCurrentDirectoryPath()).
Return: a new File object representing the opened file if the file exists and was able to be successfully opened for read. This object must be passed to closeFile() when it is no longer needed.
Return: nullptr if the named file does not exist in the file system or another error occurred (ie: insufficient permissions, allocation failure, etc).

File *(*openFileToWrite)(const char *path)

Opens a file for writing in binary mode.

Remark

This opens a file for writing. If the file does not exist, it will be created. If the file does exist, it will always be truncated to an empty file. The file pointer will initially be positioned at the beginning of the file. All writes to the file will occur at the current file pointer position. If the file needs to be opened for writing without truncating its contents, it should be opened either for append access (ie: openFileToAppend()) or for read/write access (ie: openFileToReadWrite()).

Errors

Accessible via carb::ErrorApi

Note: Error state is not changed with a non-nullptr return value
omni::core::kResultInvalidArgument - path was nullptr
omni::core::kResultNotFound - The file was not found
omni::core::kResultAccessDenied - Access was denied to the file
omni::core::kResultOutOfMemory - Allocation failure
Other errors may be reported based on the underlying platform calls

Param path: [in] The absolute or relative path for the file. This may not be nullptr. Relative paths are resolved from the current working directory (as returned from getCurrentDirectoryPath()).
Return: a new File object representing the opened file if successful. A new file will have been created if it previously did not exist. This object must be passed to closeFile() when it is no longer needed.
Return: nullptr if the named file could neither be created nor opened. This may be the result of insufficient permissions to the file or an allocation failure. A warning will be written to the default logger in this case.

File *(*openFileToAppend)(const char *path)

Opens a file for appending in binary mode.

Remark

This opens a file for appending. If the file does not exist, it will always be created. The file pointer is initially positioned at the end of the file. All writes to the file will be performed at the end of the file regardless of the current file pointer position. If random access writes are needed, the file should be opened for read/write access (ie: openFileToReadWrite()) instead.

Errors

Accessible via carb::ErrorApi

Note: Error state is not changed with a non-nullptr return value
omni::core::kResultInvalidArgument - path was nullptr
omni::core::kResultNotFound - The file was not found
omni::core::kResultAccessDenied - Access was denied to the file
omni::core::kResultOutOfMemory - Allocation failure
Other errors may be reported based on the underlying platform calls

Param path: [in] The absolute or relative path for the file. This may not be nullptr. Relative paths are resolved from the current working directory (as returned from getCurrentDirectoryPath()).
Return: a new File object representing the opened file if successful. A new file will have been created if it previously did not exist. This object must be passed to closeFile() when it is no longer needed.
Return: nullptr if the named file could neither be created nor opened. This may be the result of insufficient permissions to the file or an allocation failure. A warning will be written to the default logger in this case.

void (*closeFile)(File *file)

Closes a file returned by any of the openFileTo*() functions.

See also

openFileToRead openFileToWrite openFileToAppend openFileToReadWrite

Errors

Accessible via carb::ErrorApi

omni::core::kResultSuccess - No error occurred
omni::core::kResultInvalidArgument - file was nullptr
Other errors may be reported based on the underlying platform calls

Param file: [in] the File object representing the file to be closed. This object will no longer be valid upon return and must not be used again. This object would have been returned by a previous openFileTo*() call. If nullptr is provided, it is ignored.
Return: no return value.
Post: The File is destroyed and must not be accessed anymore.

size_t (*getFileSize)(File *file)

Gets the total size of the file.

Errors

Accessible via carb::ErrorApi

omni::core::kResultSuccess - No error occurred
Other errors may be reported based on the underlying platform calls

Note

Writable files will execute a flushFile() as part of this request.

Param file: object corresponding to an open file.
Return: The total size of the file in bytes, or 0 if an error occurs. If the file is 0 bytes, carb::ErrorApi::getError() can be queried and the result will be omni::core::kResultSuccess.

time_t (*getFileModTime)(File *file)

Gets the time of last modification to the file.

Errors

Accessible via carb::ErrorApi

omni::core::kResultSuccess - No error occurred
Other errors may be reported based on the underlying platform calls

Note

Writable files will execute a flushFile() as part of this request.

Param file: object corresponding to an open file.
Return: The time this file was last modified. If an error occurs, 0 is returned and carb::ErrorApi::getError() contains the error code.

time_t (*getModTime)(const char *path)

Gets the time of last modification to the file or directory item at path.

Errors

Accessible via carb::ErrorApi

omni::core::kResultSuccess - No error occurred
omni::core::kResultNotFound - The file was not found
Other errors may be reported based on the underlying platform calls

Param path: The path to a file or directory item; relative paths are resolved from the current working directory (as returned from getCurrentDirectoryPath()).
Return: The time the item at ‘path’ was last modified. If an error occurs, 0 is returned and carb::ErrorApi::getError() contains the error code.

time_t (*getFileCreateTime)(File *file)

Gets the time of creation of the file.

Errors

Accessible via carb::ErrorApi

omni::core::kResultSuccess - No error occurred
Other errors may be reported based on the underlying platform calls

Param file: object corresponding to an open file.
Return: The time this file was created. If an error occurs, 0 is returned and carb::ErrorApi::getError() contains the error code.

time_t (*getCreateTime)(const char *path)

Gets the time of creation of the file or directory item at path.

Errors

Accessible via carb::ErrorApi

omni::core::kResultSuccess - No error occurred
omni::core::kResultNotFound - The file was not found
Other errors may be reported based on the underlying platform calls

Param path: The path to a file or directory item; relative paths are resolved from the current working directory (as returned from getCurrentDirectoryPath()).
Return: The time the file at path was created. If an error occurs, 0 is returned and carb::ErrorApi::getError() contains the error code.

size_t (*readFileChunk)(File *file, void *chunk, size_t chunkSize)

Reads a chunk of binary data from a file.

Errors

Accessible via carb::ErrorApi

omni::core::kResultSuccess - No error occurred
omni::core::kResultFail - A failure was reported during read, getFileStatus() will report error.
Other errors may be reported based on the underlying platform calls

Param file: Object corresponding to an open file for reading in binary mode.
Param chunk: Memory to read the binary data to, at least chunkSize bytes large.
Param chunkSize: Number of bytes to read from file into ‘chunk’ memory area.
Return: Number of bytes read, this can be less than requested ‘chunkSize’ when reading the last bytes of data. Will return 0 when all data has been read from the file.

size_t (*writeFileChunk)(File *file, const void *chunk, const size_t chunkSize)

Writes a chunk of binary data to a file.

Errors

Accessible via carb::ErrorApi

omni::core::kResultSuccess - No error occurred
omni::core::kResultFail - A failure was reported during write, getFileStatus() will report error.
Other errors may be reported based on the underlying platform calls

Param file: An open file for writing in binary mode.
Param chunk: The memory buffer to write to the file.
Param chunkSize: Number of bytes from ‘chunk’ to write to the file.
Return: the number of bytes successfully written to the file. This can be less than the requested chunkSize if an error occurs (ie: disk full).
Return: 0 if no data could be written to the file.

char *(*readFileLine)(File *file, char *line, size_t maxLineSize)

Reads a line of character data from a text file (without including the line ending characters \r or \n).

Errors

Accessible via carb::ErrorApi

Note: Error state is not changed with a non-nullptr return value
omni::core::kResultSuccess - At end-of-file
omni::core::kResultFail - A failure was reported during read, getFileStatus() will report error.
Other errors may be reported based on the underlying platform calls

Note

This function considers a \n by itself to be a line ending, as well as \r\n. A \r by itself is not considered a line ending. The line endings are consumed from the file stream but are not present in the result.

Note

For maxLineSize of 0, nullptr is always returned without any change to the file read pointer. For maxLineSize of 1 when not at end-of-file, line will only contain a NUL terminator and if a line ending is at the start of the file stream it will be consumed.

Param file: A file returned from openFileToRead() or openFileToReadWrite().
Param line: The string that will receive the read line. Unlike fgets(), the result will NOT end with any line ending characters (\n or \r\n), but they will be consumed from the file stream.
Param maxLineSize: The maximum number of characters that can be read into line, including NUL terminator. If the buffer is exhausted before end-of-line is reached the buffer will be NUL terminated and thus still a proper C-style string but won’t necessarily contain the full line from the file.
Return: Returns line on each successful read, or nullptr if file is at end-of-file or an error occurs.

bool (*writeFileLine)(File *file, const char *line)

Writes a line of characters to a text file.

Errors

Accessible via carb::ErrorApi

Note: Error state is not changed unless false is returned.
omni::core::kResultFail - A failure was reported during write, getFileStatus() will report error.
Other errors may be reported based on the underlying platform calls

Param file: An file returned from openFileToWrite() or openFileToAppend().
Param line: The null-terminated string to write. A newline will always be appended to the string in the file if it is successfully written.
Return: true if the string is successfully written to the file.
Return: false if the full string could not be written to the file.

void (*flushFile)(File *file)

Flushes any unwritten data to the file.

When a file is closed, either by calling closeFile or during program termination, all the associated buffers are automatically flushed.

Errors

Accessible via carb::ErrorApi

omni::core::kResultSuccess - No error occurred
omni::core::kResultInvalidArgument - An invalid argument was provided
Other errors may be reported based on the underlying platform calls

Param file: An open file for writing or appending.

bool (*removeFile)(const char *path)

Removes (deletes) a file.

Errors

Accessible via carb::ErrorApi

Note: Error state is not changed unless false is returned
omni::core::kResultInvalidArgument - An invalid argument was provided
omni::core::kResultNotFound - The file was not found
Other errors may be reported based on the underlying platform calls

Param path: [in] The path of the file to be removed. This must not have any open file objects on it otherwise the operation will fail.
Return: true if the file was removed from the file system.
Return: false if the file could not be removed. This is often caused by either having the file still open by either the calling process or another process, or by not having sufficient permission to delete the file.

bool (*makeTempDirectory)(char *pathBuffer, size_t bufferSize)

Make a temporary directory.

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

Errors

Accessible via carb::ErrorApi

Note: Error state is not changed unless false is returned
omni::core::kResultInvalidArgument - An invalid argument was provided
omni::core::kResultInsufficientBuffer - The provided bufferSize was not sufficient
Other errors may be reported based on the underlying platform calls

Param pathBuffer: The buffer that will receive the full path to the created directory. This may not be nullptr.
Param bufferSize: The size of the buffer for storing the path. This size also includes the null terminator for the string. If this is too small to store the output path.
Return: true if the creation was successful and a path to the newly created temporary directory was returned in pathBuffer. On success, the temporary directory is guaranteed to exist and be writable by the caller. The caller is responsible for removing this directory when it is no longer needed.
Return: false if the temporary directory could not be created for any reason. In this case, the pathBuffer buffer will not be modified and its contents will be undefined.

bool (*makeDirectory)(const char *path)

Make a single directory.

Remark

This attempts to make a single new directory entry. All path components leading up to the new path must already exist for this to be expected to succeed. The path may already exist and this call will still succeed.

Remark

Note that this operation is global to the system. There is no control over what other threads or processes in the system may be simultaneously doing to the named path. It is the caller’s responsibility to gracefully handle any potential failures due to the action of another thread or process.

Errors

Accessible via carb::ErrorApi

omni::core::kResultSuccess - No error occurred
omni::core::kResultInvalidArgument - An invalid argument was provided
omni::core::kResultAlreadyExists - The directory already exists. If false is returned then a file exists that prevents creation of the directory; if true is returned then the directory already exists (not an error)
Other errors may be reported based on the underlying platform calls

Note

There is a possible race condition with another thread or process creating the same path simultaneously. If this occurs, this call will still succeed in most cases. There is an additional rare possible race condition where the file or folder could also be deleted by an external thread or process after it also beat the calling thread to creating the path. In this case, this call will fail. For this to occur there would need to be the named path created then immediately destroyed externally.

Note

This call itself is thread safe. However, the operation it performs may race with other threads or processes in the system. Since file system directories are global and shared by other processes, an external caller may create or delete the same directory as is requested here during the call. There is unfortunately no way to prevent this or make it safer since the creator or deleter of the path may not even be local to the system (ie: a network share operation was requested). The best a caller can do you be to guarantee its own threads do not simultaneously attempt to operate on the same path.

Param path: The path to the directory to create. Relative paths will be resolved from the current working directory (as returned from getCurrentDirectoryPath()). This may not be nullptr or an empty string.
Retval true: if the path did not previously exist and the creation as a folder was successful, or if the path already existed as a directory (omni::core::kResultAlreadyExists is reported)
Retval false: if the path already existed as a non-directory entry (omni::core::kResultAlreadyExists), or if the path could not be created for another reason (carb::ErrorApi will have reason)

bool (*makeDirectories)(const char *path)

Make one or more directories.

Remark

This attempts to create one or more directories. All components listed in the path will be created if they do not already exist. If one of the path components already exists as a non-directory object, the operation will fail. If creating any of the intermediate path components fails, the whole operation will fail. If any of the components already exists as a directory, it will be ignored and continue with the operation.

Errors

Accessible via carb::ErrorApi

omni::core::kResultSuccess - No error occurred
omni::core::kResultInvalidArgument - An invalid argument was provided
omni::core::kResultAlreadyExists - The directory already exists. If false is returned then a file exists that prevents creation of the directory; if true is returned then the directory already exists (not an error)
Other errors may be reported based on the underlying platform calls

Note

This call itself is thread safe. The operation itself may have a race condition with other threads or processes however. Please see makeDirectory() for more information about these possible race conditions.

Param path: The path to the directory to create. Relative paths will be resolved from the current working directory (as returned from getCurrentDirectoryPath()). This may not be nullptr or an empty string.
Retval true: if the path did not previously exist and the creation as a folder was successful, or if the path already existed as a directory (omni::core::kResultAlreadyExists is reported)
Retval false: if the path already existed as a non-directory entry (omni::core::kResultAlreadyExists), or if the path could not be created for another reason (carb::ErrorApi will have reason)

bool (*removeDirectory)(const char *path)

Remove a directory.

Errors

Accessible via carb::ErrorApi

omni::core::kResultInvalidArgument - An invalid argument was provided
omni::core::kResultNotFound - The directory was not found
Other errors may be reported based on the underlying platform calls

Note

This will never follow symbolic links. The symbolic link will be removed, but its target will not.

Note

On Windows, it is neither possible to remove the current working directory nor any directory containing it. This is because the Windows process holds an open handle to the current working directory without delete sharing permissions at all times. In order to remove the current working directory, the caller must first change the working directory to another valid path, then call removeDirectory(). On Linux, removing the current working directory is technically possible, however, doing so will leave the process in an undefined state since its working directory is no longer valid. Changing away from the working directory before calling this is still a good idea even on Linux.

Param path: The path to the directory to remove; relative paths will be resolved from the current working directory (as returned from getCurrentDirectoryPath()).
Return: true if the removal was successful, otherwise false.

bool (*copy)(const char *from, const char *to)

Copy a file.

Errors

Accessible via carb::ErrorApi

Note: Error state is not changed unless false is returned
omni::core::kResultInvalidArgument - An invalid argument was provided
omni::core::kResultNotFound - The file was not found
omni::core::kResultAlreadyExists - The target file already exists
Other errors may be reported based on the underlying platform calls

Param from: The path to a file to copy; relative paths will be resolved from the current working directory (as returned from getCurrentDirectoryPath()).
Param to: The destination filename and path; relative paths will be resolved from the current working directory (as returned from getCurrentDirectoryPath()).
Return: true if the file was copied successfully; false if an error occurs.

bool (*move)(const char *from, const char *to)

Moves (renames) a file or directory.

Errors

Accessible via carb::ErrorApi

Note: Error state is not changed unless false is returned
omni::core::kResultInvalidArgument - An invalid argument was provided
omni::core::kResultNotFound - The file was not found
omni::core::kResultAlreadyExists - The target file already exists
Other errors may be reported based on the underlying platform calls

Note

A rename to the same file will be successful with no error.

Param from: The path to a file or directory to rename; relative paths will be resolved from the current working directory (as returned from getCurrentDirectoryPath()).
Param to: The destination path; relative paths will be resolved from the current working directory (as returned from getCurrentDirectoryPath()).
Return: true if the file was moved successfully; false if an error occurs.

void (*forEachDirectoryItem)(const char *path, OnDirectoryItemFn onDirectoryItem, void *userData)

Iterate through each item in the directory.

Errors

Accessible via carb::ErrorApi

omni::core::kResultSuccess - No error occurred
omni::core::kResultInvalidArgument - An invalid argument was provided
omni::core::kResultNotFound - The path was not found
Other errors may be reported based on the underlying platform calls

Note

It is entirely possible that by the time the callback function is called for a given file or directory, that file or directory could have already been deleted, moved, or renamed by another thread or process. In this case the file information that is passed to the callback function may already be out of date. The callback function should take this into account before taking any action on the given file or directory. One possible way to detect this is to check if the DirectoryItemInfo::createdTimestamp and DirectoryItemInfo::modifiedTimestamp values are zero. The callback could also verify that the file still exists before acting on it.

Param path: The path to the directory; relative paths will be resolved from the current working directory (as returned from getCurrentDirectoryPath()).
Param onDirectoryItem: The function to call for each directory item, see OnDirectoryItemFn type
Param userData: The user data passed to the callback function for each item. May be nullptr.

void (*forEachDirectoryItemRecursive)(const char *path, OnDirectoryItemFn onDirectoryItem, void *userData)

Iterate through each item in the directory and recursive into subdirectories.

Errors

Accessible via carb::ErrorApi

omni::core::kResultSuccess - No error occurred
omni::core::kResultInvalidArgument - An invalid argument was provided
omni::core::kResultNotFound - The path was not found
Other errors may be reported based on the underlying platform calls

Note

This will follow symbolic links.

Note

It is entirely possible that by the time the callback function is called for a given file or directory, that file or directory could have already been deleted, moved, or renamed by another thread or process. In this case the file information that is passed to the callback function may already be out of date. The callback function should take this into account before taking any action on the given file or directory. One possible way to detect this is to check if the DirectoryItemInfo::createdTimestamp and DirectoryItemInfo::modifiedTimestamp values are zero. The callback could also verify that the file still exists before acting on it.

Param path: The path to the directory; relative paths will be resolved from the current working directory (as returned from getCurrentDirectoryPath()).
Param onDirectoryItem: The function to call for each directory item, see IFileSystem::DirectoryCallback type
Param userData: The user data passed to the callback function for each item.

SubscriptionId (*subscribeToChangeEvents)(const char *path, OnChangeEventFn onChangeEvent, void *userData)

Subscribes to listen on change events on a path.

Errors

Accessible via carb::ErrorApi

Note: Error state is not changed unless kInvalidSubscriptionId is returned
omni::core::kResultInvalidArgument - An invalid argument was provided
omni::core::kResultFail - A system error occurred
Other errors may be reported based on the underlying platform calls

Note

The change subscriptions on directories are not recursive. If you watch a directory, you will not get change events for files/directories within subdirectories.

Note

Modifications to subdirectories (e.g. creating/deleting a file inside it) will not produce change events. OM-1071: there is a bug in the Windows implementation where deleting a file in a subdirectory produces a ChangeAction::eModified event.

Note

If path points to a directory, deleting the directory will produce a ChangeAction::eDeleted event and then no more events will be produced from the stream, even if the directory is created again. This behavior differs if path points to a file. Change events will continue to be produced for a file after it’s been deleted if it’s created again.

Note

Mac OS only appears to support ~512 subscriptions in a process (this value was determined experimentally). For subscription 513+, notifications are no longer sent.

Param path: The path to subscribe to. This path must be an existing file or directory on disk.
Param onChangeEvent: The callback function to be called when the events are fired.
Param userData: The user data passed to the callback function for each item.
Retval kInvalidSubscriptionId: if path does not exist, or some other error occurred (see ErrorApi to determine the reason)
Return: subscription id if the path was successfully subscribed

void (*unsubscribeToChangeEvents)(SubscriptionId subscriptionId)

Unsubscribes from listening to change events on a path.

Errors

Accessible via carb::ErrorApi

omni::core::kResultSuccess - No error occurred
omni::core::kResultInvalidArgument - An invalid argument was provided
omni::core::kResultNotFound - The given subscriptionId was not found
omni::core::kResultFail - A system error occurred
Other errors may be reported based on the underlying platform calls

Note

It is safe to call this from within the callback passed to subscribeToChangeEvents(). The function will not return until the subscription callback is guaranteed to be exited by all other threads.

Param subscription: Subscription id

int64_t (*getFilePosition)(File *file)

retrieves the current file pointer position for an open file.

Remark

This retrieves the current location of the file pointer in a file that has been opened for read, write, or append. The offset is always returned in bytes. The current file position may be beyond the end of the file if the file pointer was recently placed beyond the end of the file. However, this does not actually reflect the size of the file until at least one byte is written into it at the new position beyond the file’s end.

Errors

Accessible via carb::ErrorApi

omni::core::kResultSuccess - No error occurred
Other errors may be reported based on the underlying platform calls

Param file: [in] the file object to retrieve the current position for. This may have been opened for read or write. Files that were opened for append will always write at the end of the file regardless of the current file position. The file pointer’s current position is typically unused or undefined in the append case.
Return: the current position in the file in bytes relative to the beginning.
Return: -1 if the file’s position could not be retrieved.

bool (*setFilePosition)(File *file, int64_t offsetFromWhence, FileWhence whence)

sets the new file pointer position for an open file.

Remark

This attempts to reposition the file pointer in an open file. The new absolute position may not be negative once combined with whence. If the new absolute position is beyond the current end of the file, the file will not be extended until at least one byte is written into the file at that new position or the file is truncated at the current position with truncateFileAtCurrentPosition(). When it is written to or truncated with a larger size than previous, the new space will be filled with zeros. Note however, that if the file pointer is set beyond the end of the file, the getFilePosition() call will return that same position even though it is larger than the file currently is.

Errors

Accessible via carb::ErrorApi

Note: Error state is not changed unless false is returned
omni::core::kResultInvalidArgument - an invalid argument was supplied
omni::core::kResultFail - an underlying platform call failed
Other errors may be reported based on the underlying platform calls

Param file: [in] the file object to set the current position for. This may have been opened for read or write. Files that were opened for append will always write at the end of the file regardless of the current file position. The file pointer’s current position is typically unused or undefined in the append case.
Param offsetFromWhence: [in] the new position for the file pointer relative to the location specified in whence. This value may be negative only if whence is not FileWhence::eBegin. This may specify an index beyond the current end of the file when combined with whence.
Param whence: [in] the fixed location in the file to move the file pointer relative to.
Return: true if the file position was successfully set.
Return: false if the file position could not be set or was invalid.

bool (*truncateFileAtCurrentPosition)(File *file)

truncates a file at the current file position.

Remark

This truncates a file at the current file pointer position. This can be used to extend a file without needing to write anything to it by opening the file, setting the file pointer to the desired size with setFilePointer(), then calling this function to set the new end of the file. The new area of the file will be filled with zeros if it was extended. If the file is being shortened, all data in the file beyond the current file pointer will be removed.

Errors

Accessible via carb::ErrorApi

Note: Error state is not changed unless false is returned
omni::core::kResultInvalidArgument - An invalid argument was provided
omni::core::kResultAccessDenied - Attempting to truncate a read-only file
Other errors may be reported based on the underlying platform calls

Param file: [in] the file to be truncated. This must have been opened for write or append.
Retval true: if the file was successfully truncated.
Retval false: if the file could not be truncated for any reason.

File *(*openFileToReadWrite)(const char *path)

opens the file for read and write in binary mode.

Remark

This opens a file for both read and write access. If the file already exists, it is not truncated. If the file does not exist, it will be created. The file pointer is initially placed at the beginning of the file. All writes to the file will occur at the current file pointer location.

Errors

Accessible via carb::ErrorApi

Note: Error state is not changed unless nullptr is returned
omni::core::kResultInvalidArgument - path was nullptr
omni::core::kResultNotFound - The file was not found
omni::core::kResultAccessDenied - Access was denied to the file
omni::core::kResultOutOfMemory - Allocation failure
Other errors may be reported based on the underlying platform calls

Param path: [in] the absolute or relative path to the file to open. This may not be nullptr. Relative paths are resolved from the current working directory (as returned from getCurrentDirectoryPath()).
Return: a new open file stream object if the file is successfully opened. This file object must be closed with closeFile() when it is no longer needed.
Return: nullptr if the file could not be opened for any reason. This can occur if the file could not be created or there are insufficient permissions to access the file, or an allocation failure occurred.

FileStatus (*getFileStatus)(File *file)

retrieves the current status of a file stream object.

Remark

This retrieves the current status of a file stream object. The status allows the caller to differentiate an error from an end-of-file condition for the last file operation. The error condition on the file will be reset after each operation after being stored for later retrieval. The file stream status value will remain valid until the next operation is performed on the file.

Errors: This function does not modify the calling thread’s error state

Note

As with all other file operations, retrieving this status is not thread safe and could change if another thread performs an unprotected operation on the same stream. It is the caller’s responsibility to ensure operations on the file stream are appropriately protected.

Note

The file status will not be modified by calls to getFileSize(), getFileModTime(), flushFile(), or getFilePosition().

Param file: [in] an open file stream to check the status of.
Retval FileStatus::eOk: if the file stream is still in a valid state and more read or write operation may potentially succeed.
Retval FileStatus::eError: if the file stream has encountered an error of any kind. This may include a partial write due to a full disk or a disk quota being reached.
Retval FileStatus::eEof: if a file stream opened for read has already read the last bytes in the file. A future call to readFile*() will simply return 0 or nullptr from the same file position.

bool (*getFileInfo)(const char *path, FileInfo *info)

fills the FileInfo struct with info about the given file.

Errors

Accessible via carb::ErrorApi

Note: Error state is not changed unless false is returned
omni::core::kResultInvalidArgument - info was nullptr or path was empty or nullptr
omni::core::kResultNotFound - The file was not found
omni::core::kResultAccessDenied - Access was denied to the file
Other errors may be reported based on the underlying platform calls

Param path: The path to the file.
Param info: The struct populated with info about the file.
Return: true if information was gathered; false if an error occurs.

time_t (*getCurrentTime)()

Returns the current time of the file system.

Errors: This function does not change error state

Return: the current time as via time(0)

bool (*isReadable)(const char *path)

Tests whether it’s possible to read a file or directory.

Errors

Accessible via carb::ErrorApi

Note: Error state is not changed unless false is returned
omni::core::kResultInvalidArgument - path is nullptr
omni::core::kResultNotFound - The file was not found
omni::core::kResultAccessDenied - Access was denied to the file
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.

Param path: The absolute or relative path to test for readability. Relative paths are resolved from the current working directory (as returned from the getCurrentDirectoryPath() function). This may not be nullptr or an empty string.
Return: true if the given file or directory exists and is readable by the calling user. Returns false if the file or directory doesn’t exist or the user does not have permission to read from it. For a directory, readability represents permission to list the contents of the directory.

size_t (*makeCanonicalPathEx2)(const char *path, const char *base, CanonicalFlags flags, char *buffer, size_t bufferSize)

Use platform functions to build canonical path relative to the base root.

The path must exist if fCanonicalFlagCheckExists is passed in the flags parameter.

If returned size is greater than passed bufferSize, then nothing is written to the buffer. If returned size is 0, then canonical path failed to be built or doesn’t exist.

Errors

Accessible via carb::ErrorApi. This function always modifies the error state.

omni::core::kResultSuccess - No error occurred
omni::core::kResultInvalidArgument - path was nullptr
omni::core::kResultNotFound - The file was not found
omni::core::kResultInsufficientBuffer - The provided buffer was too small to receive the canonicalized string. The contents of buffer are unchanged and the return value is the number of bytes required (including the NUL terminator).
omni::core::kResultNullPointer - No buffer was provided, so nothing was written. The return value is the number of bytes required to contain the canonical path (include the NUL terminator).
Other errors may be reported based on the underlying platform calls

Note

By default, this assumes that the requested file exists on the filesystem. On Linux, the existence of the file will still be checked as a side effect of the operation. On Windows however, no explicit check for the file existing in the filesystem will be performed unless the fCanonicalFlagCheckExists is used.

Param path: The absolute or relative path to canonicalize.
Param base: The base path to resolve relative path against. This can be nullptrto use the working directory (as returned from getCurrentDirectoryPath()) to resolve the relative path.
Param flags: Flags to control the behavior of this operation.
Param buffer: The buffer to write the canonical path to. This may be nullptr if only the required size of the buffer is needed.
Param bufferSize: The size of the buffer buffer in bytes.
Return: The number of bytes written to the buffer buffer if the buffer is large enough. If the buffer is not large enough, nothing will be written to the buffer and the required size of the buffer in bytes will be returned. If an error occurs, 0 is returned.

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.