Defines file system input/output functions.
Well-defined value for an invalid file handle.
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.
kSbFileOkkSbFileErrorFailedkSbFileErrorInUsekSbFileErrorExistskSbFileErrorNotFoundkSbFileErrorAccessDeniedkSbFileErrorTooManyOpenedkSbFileErrorNoMemorykSbFileErrorNoSpacekSbFileErrorNotADirectorykSbFileErrorInvalidOperationkSbFileErrorSecuritykSbFileErrorAbortkSbFileErrorNotAFilekSbFileErrorNotEmptykSbFileErrorInvalidUrlkSbFileErrorIOkSbFileErrorMaxFlags 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.
kSbFileOpenOnly
kSbFileCreateOnly
kSbFileOpenAlways
does not already exist.
kSbFileCreateAlways
path or creates a new file at that path.
kSbFileOpenTruncated
or overwrites an existing file at that path.
kSbFileRead
only if it exists.
kSbFileWrite
kSbFileAsync
This explicit mapping matches both FILE_ on Windows and SEEK_ on Linux.
kSbFileFromBeginkSbFileFromCurrentkSbFileFromEndA handle to an open file.
typedef SbFilePrivate* SbFile
Used to hold information about a file.
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.
SbTime last_modified
The last modified time of a file.
SbTime last_accessed
The last accessed time of a file.
SbTime creation_time
The creation time of a file.
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.
bool SbFileAtomicReplace(const char *path, const char *data, int64_t data_size)
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.
bool SbFileCanOpen(const char *path, int flags)
Closes file. The return value indicates whether the file was closed successfully.
file: The absolute path of the file to be closed.
bool SbFileClose(SbFile file)
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.
bool SbFileDelete(const char *path)
Indicates whether a file or directory exists at path.
path: The absolute path of the file or directory being checked.
bool SbFileExists(const char *path)
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.
bool SbFileFlush(SbFile file)
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.
bool SbFileGetInfo(SbFile file, SbFileInfo *out_info)
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.
bool SbFileGetPathInfo(const char *path, SbFileInfo *out_info)
Returns whether the given file handle is valid.
static bool SbFileIsValid(SbFile file)
Converts an ISO fopen() mode string into flags that can be equivalently passed into SbFileOpen().
mode: The mode string to be converted into flags.
int SbFileModeStringToFlags(const char *mode)
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.
SbFile SbFileOpen(const char *path, int flags, bool *out_created, SbFileError *out_error)
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.
int SbFileRead(SbFile file, char *data, int size)
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.
static int SbFileReadAll(SbFile file, char *data, int size)
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.
int64_t SbFileSeek(SbFile file, SbFileWhence whence, int64_t offset)
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.
bool SbFileTruncate(SbFile file, int64_t length)
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.
int SbFileWrite(SbFile file, const char *data, int size)
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.
static int SbFileWriteAll(SbFile file, const char *data, int size)