Starboard Module Reference: file.h

Defines file system input/output functions.

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
  • kSbFileErrorMax - Put new entries here and increment 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 - Opens a file, only if it exists.
  • kSbFileCreateOnly - Creates a new file, only if it does not already exist.
  • kSbFileOpenAlways - Opens an existing file at the specified path or creates a new file at that path.
  • kSbFileCreateAlways - Creates a new file at the specified path or overwrites an existing file at that path.
  • kSbFileOpenTruncated - Opens a file and truncates it to zero, only if it exists.
  • kSbFileRead
  • kSbFileWrite
  • kSbFileAsync - May allow asynchronous I/O on some platforms, meaning that calls to Read or Write will only return the data that is readily available.

SbFileWhence

This explicit mapping matches both FILE_ on Windows and SEEK_ on Linux.

Values

  • kSbFileFromBegin
  • kSbFileFromCurrent
  • kSbFileFromEnd

Structs

SbFileInfo

Used to hold information about a file.

Members

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.
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.

SbFilePrivate

Private structure representing an open file.

Functions

SbFileCanOpen

Description

Indicates whether SbFileOpen() with the given flags is allowed for path.

Declaration and definitions

SB_EXPORT bool SbFileCanOpen(const char* path, int flags);

#include "starboard/file.h"

bool SbFileCanOpen(const char* /*path*/, int /*flags*/) {
  return false;
}

Parameters

Parameters
const char*
path
The absolute path to be checked.
int
flags
The flags that are being evaluated for the given path.

SbFileClose

Description

Closes file. The return value indicates whether the file was closed successfully.

Declaration and definitions

SB_EXPORT bool SbFileClose(SbFile file);

#include "starboard/file.h"

bool SbFileClose(SbFile /*file*/) {
  return false;
}

Parameters

Parameters
SbFile
file
The absolute path of the file to be closed.

SbFileDelete

Description

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.

Declaration and definitions

SB_EXPORT bool SbFileDelete(const char* path);

#include "starboard/file.h"

bool SbFileDelete(const char* /*path*/) {
  return false;
}

Parameters

Parameters
const char*
path
The absolute path fo the file, symlink, or directory to be deleted.

SbFileExists

Description

Indicates whether a file or directory exists at path.

Declaration and definitions

SB_EXPORT bool SbFileExists(const char* path);

#include "starboard/file.h"

bool SbFileExists(const char* /*path*/) {
  return false;
}

Parameters

Parameters
const char*
path
The absolute path of the file or directory being checked.

SbFileFlush

Description

Flushes the write buffer to file. Data written via SbFileWrite is not necessarily committed until the SbFile is flushed or closed.

Declaration and definitions

SB_EXPORT bool SbFileFlush(SbFile file);

#include "starboard/file.h"

bool SbFileFlush(SbFile /*file*/) {
  return false;
}

Parameters

Parameters
SbFile
file
The SbFile to which the write buffer is flushed.

SbFileGetInfo

Description

Retrieves information about file. The return value indicates whether the file information was retrieved successfully.

Declaration and definitions

SB_EXPORT bool SbFileGetInfo(SbFile file, SbFileInfo* out_info);

#include "starboard/file.h"

bool SbFileGetInfo(SbFile /*file*/, SbFileInfo* /*out_info*/) {
  return false;
}

Parameters

Parameters
SbFile
file
The SbFile for which information is retrieved.
SbFileInfo*
out_info
The variable into which the retrieved data is placed. This variable is not touched if the operation is not successful.

SbFileGetPathInfo

Description

Retrieves information about the file at path. The return value indicates whether the file information was retrieved successfully.

Declaration and definitions

SB_EXPORT bool SbFileGetPathInfo(const char* path, SbFileInfo* out_info);

#include "starboard/file.h"

bool SbFileGetPathInfo(const char* /*path*/, SbFileInfo* /*out_info*/) {
  return false;
}

Parameters

Parameters
const char*
path
SbFileInfo*
out_info
The variable into which the retrieved data is placed. This variable is not touched if the operation is not successful.

SbFileIsValid

Description

Returns whether the given file handle is valid.

Declaration

static SB_C_INLINE bool SbFileIsValid(SbFile file) {
  return file != kSbFileInvalid;
}

Parameters

Parameters
SbFile
file

SbFileModeStringToFlags

Description

Converts an ISO fopen() mode string into flags that can be equivalently passed into SbFileOpen().

Declaration

SB_EXPORT int SbFileModeStringToFlags(const char* mode);

Parameters

Parameters
const char*
mode
The mode string to be converted into flags.

SbFileOpen

Description

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.

Declaration and definitions

SB_EXPORT SbFile SbFileOpen(const char* path,
                            int flags,
                            bool* out_created,
                            SbFileError* out_error);

#include "starboard/file.h"

SbFile SbFileOpen(const char* /*path*/,
                  int /*flags*/,
                  bool* /*out_created*/,
                  SbFileError* /*out_error*/) {
  return kSbFileInvalid;
}

Parameters

Parameters
const char*
path
The absolute path of the file to be opened.
int
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.
bool*
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.
SbFileError*
out_error
If path cannot be created, this is set to kSbFileInvalid. Otherwise, it is NULL.

SbFileRead

Description

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.

Declaration and definitions

SB_EXPORT int SbFileRead(SbFile file, char* data, int size);

#include "starboard/file.h"

int SbFileRead(SbFile /*file*/, char* /*data*/, int /*size*/) {
  return 0;
}

Parameters

Parameters
SbFile
file
The SbFile from which to read data.
char*
data
The variable to which data is read.
int
size
The amount of data (in bytes) to read.

SbFileReadAll

Description

Reads size bytes (or until EOF is reached) from file into data, starting from the beginning of the file.
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.

Declaration

static inline int SbFileReadAll(SbFile file, char* data, int size) {
  if (!SbFileIsValid(file) || size < 0) {
    return -1;
  }
  int bytes_read = 0;
  int rv;
  do {
    rv = SbFileRead(file, data + bytes_read, size - bytes_read);
    if (bytes_read <= 0) {
      break;
    }
    bytes_read += rv;
  } while (bytes_read < size);
  return bytes_read ? bytes_read : rv;
}

Parameters

Parameters
SbFile
file
The SbFile from which to read data.
char*
data
The variable to which data is read.
int
size
The amount of data (in bytes) to read.

SbFileSeek

Description

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.

Declaration and definitions

SB_EXPORT int64_t SbFileSeek(SbFile file, SbFileWhence whence, int64_t offset);

#include "starboard/file.h"

int64_t SbFileSeek(SbFile /*file*/,
                   SbFileWhence /*whence*/,
                   int64_t /*offset*/) {
  return 0;
}

Parameters

Parameters
SbFile
file
The SbFile in which the read/write position will be changed.
SbFileWhence
whence
The starting read/write position. The position is modified relative to this value.
int64_t
offset
The amount that the read/write position is changed, relative to whence.

SbFileTruncate

Description

Truncates the given file to the given length. The return value indicates whether the file was truncated successfully.

Declaration and definitions

SB_EXPORT bool SbFileTruncate(SbFile file, int64_t length);

#include "starboard/file.h"

bool SbFileTruncate(SbFile /*file*/, int64_t /*length*/) {
  return false;
}

Parameters

Parameters
SbFile
file
The file to be truncated.
int64_t
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.

SbFileWrite

Description

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.

Declaration and definitions

SB_EXPORT int SbFileWrite(SbFile file, const char* data, int size);

#include "starboard/file.h"

int SbFileWrite(SbFile /*file*/, const char* /*data*/, int /*size*/) {
  return 0;
}

Parameters

Parameters
SbFile
file
The SbFile to which data will be written.
const char*
data
The data to be written.
int
size
The amount of data (in bytes) to write.

SbFileWriteAll

Description

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.

Declaration

static inline int SbFileWriteAll(SbFile file, const char* data, int size) {
  if (!SbFileIsValid(file) || size < 0) {
    return -1;
  }
  int bytes_written = 0;
  int rv;
  do {
    rv = SbFileWrite(file, data + bytes_written, size - bytes_written);
    if (bytes_written <= 0) {
      break;
    }
    bytes_written += rv;
  } while (bytes_written < size);
  return bytes_written ? bytes_written : rv;
}

Parameters

Parameters
SbFile
file
The file to which data will be written.
const char*
data
The data to be written.
int
size
The amount of data (in bytes) to write.