Defines file system input/output functions. ## Macros ### kSbFileInvalid Well-defined value for an invalid file handle. ## Enums ### SbFileError kSbFileErrorAccessDenied is returned when a call fails because of a filesystem restriction. kSbFileErrorSecurity is returned when a security policy doesn't allow the operation to be executed. #### Values - `kSbFileOk` - `kSbFileErrorFailed` - `kSbFileErrorInUse` - `kSbFileErrorExists` - `kSbFileErrorNotFound` - `kSbFileErrorAccessDenied` - `kSbFileErrorTooManyOpened` - `kSbFileErrorNoMemory` - `kSbFileErrorNoSpace` - `kSbFileErrorNotADirectory` - `kSbFileErrorInvalidOperation` - `kSbFileErrorSecurity` - `kSbFileErrorAbort` - `kSbFileErrorNotAFile` - `kSbFileErrorNotEmpty` - `kSbFileErrorInvalidUrl` - `kSbFileErrorIO` - `kSbFileErrorMax` ### SbFileFlags Flags that define how a file is used in the application. These flags should be or'd together when passed to SbFileOpen to open or create a file. The following five flags are mutually exclusive. You must specify exactly one of them: - `kSbFileOpenAlways` - `kSbFileOpenOnly` - `kSbFileOpenTruncated` - `kSbFileCreateAlways` - `kSbFileCreateOnly` In addition, one or more of the following flags must be specified: - `kSbFileRead` - `kSbFileWrite` The `kSbFileAsync` flag is optional. #### Values - `kSbFileOpenOnly` - `kSbFileCreateOnly` - `kSbFileOpenAlways` Creates a new file, only if it does not already exist. - `kSbFileCreateAlways` Opens an existing file at the specified path or creates a new file at that path. - `kSbFileOpenTruncated` Creates a new file at the specified path or overwrites an existing file at that path. - `kSbFileRead` Opens a file and truncates it to zero, only if it exists. - `kSbFileWrite` - `kSbFileAsync` ### SbFileWhence This explicit mapping matches both FILE_ on Windows and SEEK_ on Linux. #### Values - `kSbFileFromBegin` - `kSbFileFromCurrent` - `kSbFileFromEnd` ## Typedefs ### SbFile A handle to an open file. #### Definition typedef SbFilePrivate* SbFile ## Structs ### SbFileInfo Used to hold information about a file. #### Members - `int64_t size` The size of the file in bytes. Undefined when is_directory is true. - `bool is_directory` Whether the file corresponds to a directory. - `bool is_symbolic_link` Whether the file corresponds to a symbolic link. - `int64_t last_modified` The last modified time of a file - microseconds since Windows epoch UTC. - `int64_t last_accessed` The last accessed time of a file - microseconds since Windows epoch UTC. - `int64_t creation_time` The creation time of a file - microseconds since Windows epoch UTC. ## Functions ### SbFileAtomicReplace Replaces the content of the file at `path` with `data`. Returns whether the contents of the file were replaced. The replacement of the content is an atomic operation. The file will either have all of the data, or none. `path`: The path to the file whose contents should be replaced. `data`: The data to replace the file contents with. `data_size`: The amount of `data`, in bytes, to be written to the file. #### Declaration bool SbFileAtomicReplace(const char *path, const char *data, int64_t data_size) ### SbFileCanOpen DEPRECATED with SB_API_VERSION 16 Indicates whether SbFileOpen() with the given `flags` is allowed for `path`. `path`: The absolute path to be checked. `flags`: The flags that are being evaluated for the given `path`. #### Declaration bool SbFileCanOpen(const char *path, int flags) ### SbFileClose DEPRECATED with SB_API_VERSION 16 Closes `file`. The return value indicates whether the file was closed successfully. `file`: The absolute path of the file to be closed. #### Declaration bool SbFileClose(SbFile file) ### SbFileDelete DEPRECATED with SB_API_VERSION 16 Deletes the regular file, symlink, or empty directory at `path`. This function is used primarily to clean up after unit tests. On some platforms, this function fails if the file in question is being held open. `path`: The absolute path of the file, symlink, or directory to be deleted. #### Declaration bool SbFileDelete(const char *path) ### SbFileExists Indicates whether a file or directory exists at `path`. `path`: The absolute path of the file or directory being checked. #### Declaration bool SbFileExists(const char *path) ### SbFileFlush DEPRECATED with SB_API_VERSION 16 Flushes the write buffer to `file`. Data written via SbFileWrite is not necessarily committed until the SbFile is flushed or closed. `file`: The SbFile to which the write buffer is flushed. #### Declaration bool SbFileFlush(SbFile file) ### SbFileGetInfo DEPRECATED with SB_API_VERSION 16 Retrieves information about `file`. The return value indicates whether the file information was retrieved successfully. `file`: The SbFile for which information is retrieved. `out_info`: The variable into which the retrieved data is placed. This variable is not touched if the operation is not successful. #### Declaration bool SbFileGetInfo(SbFile file, SbFileInfo *out_info) ### SbFileGetPathInfo DEPRECATED with SB_API_VERSION 16 Retrieves information about the file at `path`. The return value indicates whether the file information was retrieved successfully. `file`: The absolute path of the file for which information is retrieved. `out_info`: The variable into which the retrieved data is placed. This variable is not touched if the operation is not successful. #### Declaration bool SbFileGetPathInfo(const char *path, SbFileInfo *out_info) ### SbFileIsValid Returns whether the given file handle is valid. #### Declaration static bool SbFileIsValid(SbFile file) ### SbFileModeStringToFlags DEPRECATED with SB_API_VERSION 16 Converts an ISO `fopen()` mode string into flags that can be equivalently passed into SbFileOpen(). `mode`: The mode string to be converted into flags. #### Declaration int SbFileModeStringToFlags(const char *mode) ### SbFileOpen DEPRECATED with SB_API_VERSION 16 Opens the file at `path`, which must be absolute, creating it if specified by `flags`. The read/write position is at the beginning of the file. Note that this function only guarantees the correct behavior when `path` points to a file. The behavior is undefined if `path` points to a directory. `path`: The absolute path of the file to be opened. `flags`: `SbFileFlags` that determine how the file is used in the application. Among other things, `flags` can indicate whether the application should create `path` if `path` does not already exist. `out_created`: Starboard sets this value to `true` if a new file is created or if an old file is truncated to zero length to simulate a new file, which can happen if the `kSbFileCreateAlways` flag is set. Otherwise, Starboard sets this value to `false`. `out_error`: If `path` cannot be created, this is set to `kSbFileInvalid`. Otherwise, it is `NULL`. #### Declaration SbFile SbFileOpen(const char *path, int flags, bool *out_created, SbFileError *out_error) ### SbFileRead DEPRECATED with SB_API_VERSION 16 Reads `size` bytes (or until EOF is reached) from `file` into `data`, starting at the file's current position. The return value specifies the number of bytes read or `-1` if there was an error. Note that this function does NOT make a best effort to read all data on all platforms; rather, it just reads however many bytes are quickly available. However, this function can be run in a loop to make it a best-effort read. `file`: The SbFile from which to read data. `data`: The variable to which data is read. `size`: The amount of data (in bytes) to read. #### Declaration int SbFileRead(SbFile file, char *data, int size) ### SbFileReadAll DEPRECATED with SB_API_VERSION 16 Reads `size` bytes (or until EOF is reached) from `file` into `data`, starting at the file's current position. The return value specifies the number of bytes read or `-1` if there was an error. Note that, unlike `SbFileRead`, this function does make a best effort to read all data on all platforms. As such, it is not intended for stream-oriented files but instead for cases when the normal expectation is that `size` bytes can be read unless there is an error. `file`: The SbFile from which to read data. `data`: The variable to which data is read. `size`: The amount of data (in bytes) to read. #### Declaration static int SbFileReadAll(SbFile file, char *data, int size) ### SbFileSeek DEPRECATED with SB_API_VERSION 16 Changes the current read/write position in `file`. The return value identifies the resultant current read/write position in the file (relative to the start) or `-1` in case of an error. This function might not support seeking past the end of the file on some platforms. `file`: The SbFile in which the read/write position will be changed. `whence`: The starting read/write position. The position is modified relative to this value. `offset`: The amount that the read/write position is changed, relative to `whence`. #### Declaration int64_t SbFileSeek(SbFile file, SbFileWhence whence, int64_t offset) ### SbFileTruncate DEPRECATED with SB_API_VERSION 16 Truncates the given `file` to the given `length`. The return value indicates whether the file was truncated successfully. `file`: The file to be truncated. `length`: The expected length of the file after it is truncated. If `length` is greater than the current size of the file, then the file is extended with zeros. If `length` is negative, then the function is a no-op and returns `false`. #### Declaration bool SbFileTruncate(SbFile file, int64_t length) ### SbFileWrite DEPRECATED with SB_API_VERSION 16 Writes the given buffer into `file` at the file's current position, overwriting any data that was previously there. The return value identifies the number of bytes written, or `-1` on error. Note that this function does NOT make a best effort to write all data; rather, it writes however many bytes can be written quickly. Generally, this means that it writes however many bytes as possible without blocking on IO. Run this function in a loop to ensure that all data is written. `file`: The SbFile to which data will be written. `data`: The data to be written. `size`: The amount of data (in bytes) to write. #### Declaration int SbFileWrite(SbFile file, const char *data, int size) ### SbFileWriteAll DEPRECATED with SB_API_VERSION 16 Writes the given buffer into `file`, starting at the beginning of the file, and overwriting any data that was previously there. Unlike SbFileWrite, this function does make a best effort to write all data on all platforms. The return value identifies the number of bytes written, or `-1` on error. `file`: The file to which data will be written. `data`: The data to be written. `size`: The amount of data (in bytes) to write. #### Declaration static int SbFileWriteAll(SbFile file, const char *data, int size)