\[ \newcommand{\ListType}{{\text{List}}} \newcommand{\ListEmpty}{{\left[\right]}} \newcommand{\ListLength}[1]{{\ell\left(#1\right)}} \newcommand{\ListAt}[2]{{{#1}_{#2}}} \]
Home

Michael Heilmann's Arcadia Ring 2

This is the documentation for Michael Heilmann's Arcadia Ring 2. Arcadia Ring 2 facilitates the creation of C programs - in particular interpreters - that are portable, maintainable, as well as safe. Arcadia Ring 2 is available at michaelheilmann.com/Arcadia/Ring2.

Features:

Files

You can find the sources of Arcadia Ring 2 in my GitHub repository https://github.com/michaelheilmann/michaelheilmann.com. The subdirectory of Arcadia Ring 2 in the repository is here https://github.com/michaelheilmann/michaelheilmann.com-arcadia/tree/main/Runtime/Ring2.

Arcadia Ring 2 supports various platforms (including but not restricted to Windows, Linux, and many more), however, we currently only officially support Windows. For instructions on how to build, test, and use Arcadia Ring 1, refer to README.md in the root folder of the repository.

Further References

Arcadia Ring 2 relies on Arcadia Ring 1 and Arcadia ARMS.

Documentation

Arcadia_ExistingFilePolicy

typedef enum Arcadia_ExistingFilePolicy Arcadia_ExistingFilePolicy; An enumeration of policies for opening a file in case of that the file exists. The enumeration elements cannot be combined.

Elements

Arcadia_ExistingFilePolicy_Retain
Retain the file contents.
Arcadia_ExistingFilePolicy_Truncate
Truncate the file contants.

Arcadia_FileAccessMode

typedef enum Arcadia_FileAccessMode Arcadia_FileAccessMode; An enumeration of file access modes. The enumeration elements can be combined.

Elements

Arcadia_FileAccessMode_Read
Read access. Can be combined with Arcadia_FileAccessMode_Write.
Arcadia_FileAccessMode_Write
Write access. Can be combined with Arcadia_FileAccessMode_Read.
Arcadia_FileAccessMode_ReadWrite
Read and write access. Alias for Arcadia_FileAccessMode_Read|Arcadia_FileAccessMode_Write and for Arcadia_FileAccessMode_WriteRead.
Arcadia_FileAccessMode_WriteRead
Write and read access. Alias for Arcadia_FileAccessMode_Write|Arcadia_FileAccessMode_Read and for Arcadia_FileAccessMode_ReadWrite.

Arcadia_FileHandle

Arcadia_FileHandle extends Arcadia_Object.

Arcadia_FileHandle represents a operating system file handle.

Arcadia_FileHandle_create

Arcadia_FileHandle*
Arcadia_FileHandle_create
  (
    Arcadia_Thread* thread,
    Arcadia_FileSystem* fileSystem
  ) Create a file handle. The file handle is closed.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_FileSystem* self
A pointer to the backing Arcadia_FileSystem object.

Return value

A pointer to the file handle.

Arcadia_FileHandle_close

void
Arcadia_FileHandle_close
  (
    Arcadia_Thread* thread,
    Arcadia_FileHandle* self
  ) Close this file handle.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_FileHandle* self
A pointer to this file handle.

Arcadia_FileHandle_openForReading

void
Arcadia_FileHandle_openForReading
  (
    Arcadia_Thread* thread,
    Arcadia_FileHandle* self,
    Arcadia_FilePath* path
  ) Open a file for reading. If the file is open, it is closed before trying to re-open it.

Parameters

A pointer to the Arcadia_Thread object.
Arcadia_FileHandle* self
A pointer to this file handle.
Arcadia_FilePath* path
The file path of the file to read from.

Errors

Arcadia_Status_ArgumentValueInvalid
self is a null pointer.
Arcadia_Status_ArgumentValueInvalid
path is a null pointer.
Arcadia_Status_FileSystemOperationFailed
Opening the file failed.

Arcadia_FileHandle_openForWriting

void
Arcadia_FileHandle_openForWriting
  (
    Arcadia_FileHandle* self,
    Arcadia_FilePath* path
  ) Open a file for writing. If the file is open, it is closed before trying to re-open it.

Parameters

Arcadia_FileHandle* self
A pointer to this file handle.
Arcadia_FilePath* path
The file path of the file to write to.

Errors

Arcadia_Status_ArgumentValueInvalid
self is a null pointer.
Arcadia_Status_ArgumentValueInvalid
path is a null pointer.
Arcadia_Status_FileSystemOperationFailed
Opening the file failed.

Arcadia_FileHandle_isClosed

Arcadia_BooleanValue
Arcadia_FileHandle_isClosed
  (
    Arcadia_FileHandle const* self
  ) Get if this file handle is closed.

Parameters

Arcadia_FileHandle const* self
A pointer to this file handle.

Return value

Arcadia_BooleanValue_True if this file handle is closed. Arcadia_BooleanValue_False otherwise.

Arcadia_FileHandle_isOpened

Arcadia_BooleanValue
Arcadia_FileHandle_isOpened
  (
    Arcadia_FileHandle const* self
  ) Get if this file handle is opened.

Parameters

Arcadia_FileHandle const* self
A pointer to this file handle.

Return value

Arcadia_BooleanValue_True if this file handle is opened. Arcadia_BooleanValue_False otherwise.

Arcadia_FileHandle_isOpenedForReading

Arcadia_BooleanValue
Arcadia_FileHandle_isOpenedForReading
  (
    Arcadia_FileHandle const* self
  ) Get if this file handle is opened for reading.

Parameters

Arcadia_FileHandle const* self
A pointer to this file handle.

Return value

Arcadia_BooleanValue_True if this file handle is opened for reading. Arcadia_BooleanValue_False otherwise.

Arcadia_FileHandle_isOpenedForWriting

Arcadia_BooleanValue
Arcadia_FileHandle_isOpenedForWriting
  (
    Arcadia_FileHandle const* self
  ) Get if this file handle is opened for writing.

Parameters

Arcadia_FileHandle const* self
A pointer to this file handle.

Return value

Arcadia_BooleanValue_True if this file handle is opened for writing. Arcadia_BooleanValue_False otherwise.

Arcadia_FileHandle_write

void
Arcadia_FileHandle_write
  (
    Arcadia_FileHandle* self,
    void const* p,
    Arcadia_SizeValue bytesToWrite
  ) Write Bytes to this file handle.

Parameters

Arcadia_FileHandle* self
A pointer to this file handle.
void const* bytes
A pointer to an array of bytesToWrite Bytes.
Arcadia_SizeValue bytesToWrite
The number of Bytes in the array pointed to by bytes.
Arcadia_SizeValue* bytesWritten
A pointer to a Arcadia_SizeValue variable.

Success

*bytesWritten is assigned the actual number of Bytes written.

Errors

Arcadia_Status_ArgumentValueInvalid
self is a null pointer.
Arcadia_Status_ArgumentValueInvalid
bytes is a null pointer.
Arcadia_Status_OperationInvalid
The file is not opened for writing.
Arcadia_Status_FileSystemOperationFailed
Writing failed.

Arcadia_FileHandle_read

void
Arcadia_FileHandle_read
  (
  Arcadia_FileHandle* self,
  void const* bytes,
  Arcadia_SizeValue bytesToRead,
  Arcadia_SizeValue* bytesRead
  ) Read Bytes from this file handle.

Parameters

Arcadia_FileHandle* self
A pointer to this file handle.
void const* bytes
A pointer to an array of bytesToWrite Bytes.
Arcadia_SizeValue bytesToRead
The number of Bytes to read from the the array pointed to by bytes.
Arcadia_SizeValue* bytesRead
A pointer to a Arcadia_SizeValue variable.

Success

*bytesRead is assigned the actual number of Bytes read. The number of Bytes read is 0 if the end of the file was reached.

Errors

Arcadia_Status_ArgumentValueInvalid
self is a null pointer.
Arcadia_Status_ArgumentValueInvalid
bytes is a null pointer.
Arcadia
bytesRead is a null pointer.
Arcadia_Status_OperationInvalid
The file is not opened for writing.
Arcadia_Status_FileSystemOperationFailed
Writing failed.

Arcadia_FilePath

Arcadia_FilePath extends Arcadia_Object.

Arcadia_FilePath represents a file path.

create

Arcadia_FilePath*
Arcadia_FilePath_create
  (
    Arcadia_Thread* thread
  ) Create the empty file path.

Parameters

A pointer to the Arcadia_Thread object.

Return value

A pointer to the file path.

Arcadia_FilePath_parseGeneric

Arcadia_FilePath*
Arcadia_FilePath_parseGeneric
  (
    Arcadia_Thread* thread,
    void const* bytes,
    Arcadia_SizeValue numberOfBytes
  ) Parse a file path in the generic format.

Parameters

A pointer to the Arcadia_Thread object.
bytes
A pointer to an array of numberOfBytes Bytes.
numberOfBytes
The number of Bytes in the array pointed to by bytes Bytes.

Return value

A pointer to the file path.

Errors

Arcadia_Status_ArgumentValueInvalid
self is a null pointer.
Arcadia_Status_ArgumentValueInvalid
bytes is a null pointer.
Arcadia_Status_FileSystemOperationFailed
Opening the file failed.

Arcadia_FilePath_parseNative

Arcadia_FilePath*
Arcadia_FilePath_parseNative
  (
    Arcadia_Thread* thread,
    void const* bytes,
    Arcadia_SizeValue numberOfBytes
  ) Parse a file path in the native format.

Parameters

A pointer to the Arcadia_Thread object.
bytes
A pointer to an array of numberOfBytes Bytes.
numberOfBytes
The number of Bytes in the array pointed to by bytes Bytes.

Return value

A pointer to the file path.

Arcadi_FilePath_parseUnix

Arcadia_FilePath*
Arcadia_FilePath_parseUnix
  (
    Arcadia_Thread* thread,
    void const* bytes,
    Arcadia_SizeValue numberOfBytes
  ) Parse a file path in the Unix format.

Parameters

A pointer to the Arcadia_Thread object.
bytes
A pointer to an array of numberOfBytes Bytes.
numberOfBytes
The number of Bytes in the array pointed to by bytes Bytes.

Return value

A pointer to the file path.

Arcadia_FilePath_parseWindows

Arcadia_FilePath*
Arcadia_FilePath_parseWindows
  (
    Arcadia_Thread* thread,
    void const* bytes,
    Arcadia_SizeValue numberOfBytes
  ) Parse a file path in the Windows format.

Parameters

A pointer to the Arcadia_Thread object.
bytes
A pointer to an array of numberOfBytes Bytes.
numberOfBytes
The number of Bytes in the array pointed to by bytes Bytes.

Return value

A pointer to the file path.

Arcadia_FilePath_toNative

Arcadia_String*
Arcadia_FilePath_toNative
  (
    Arcadia_Thread* thread,
    Arcadia_FilePath* self
  ) Convert a file path to the native format.

Parameters

A pointer to the Arcadia_Thread object.
self
A pointer to this file path.

Return value

A pointer to the string.

Arcadia_FileSystem

Arcadia_FileSystem extends Arcadia_Object.

Arcadia_FileSystem provides access to the file system.

Arcadia_FileSystem_createDirectoryIterator

Arcadia_DirectoryIterator*br> Arcadia_FileSystem_createDirectoryIterator
  (
    Arcadia_Thread* thread,
    Arcadia_FileSystem* self,
    Arcadia_FilePath* path
  ) Create a directory iterator.

Parameters

A pointer to the Arcadia_Thread object.
A pointer to this Arcadia_FileSystem object.
A pointer to the path of the directory to search in.

Return value

A pointer to the directory iterator.

Errors

Arcadia_Status_ArgumentValueInvalid
self is a null pointer.
Arcadia_Status_ArgumentValueInvalid
path is a null pointer.

Arcadia_FileSystem_createFileHandle

Arcadia_FileHandle*
Arcadia_FileSystem_createFileHandle
  (
    Arcadia_Thread* thread,
    Arcadia_FileSystem* self
  ) Create a file handle. The file handle is in closed state.

Parameters

A pointer to the Arcadia_Thread object.
A pointer to this Arcadia_FileSystem object.

Return value

A pointer to the file handle.

Errors

Arcadia_Status_ArgumentValueInvalid
self is a null pointer.

Arcadia_FileSystem_deleteDirectoryFile

void
Arcadia_FileSystem_deleteDirectoryFile
  (
    Arcadia_Thread* thread,
    Arcadia_FileSystem* self,
    Arcadia_FilePath* path
  ) Delete a regular file.

Parameters

A pointer to the Arcadia_Thread object.
A pointer to this Arcadia_FileSystem object.
Arcadia_FilePath* path
The path to the file.

Errors

Arcadia_Status_NotEmpty
The directory was not found.
Arcadia_Status_ArgumentValueInvalid
self is a null pointer.
Arcadia_Status_ArgumentValueInvalid
path is a null pointer.
Arcadia_Status_AccessDenied
Access to the file was denied.
Arcadia_Status_NotFound
The file was not found.
Arcadia_Status_OperationFailed
The file is not found, the file is not a regular file, or deletion failed.

Arcadia_FileSystem_deleteFile

void
Arcadia_FileSystem_deleteFile
  (
    Arcadia_Thread* thread,
    Arcadia_FileSystem* self,
    Arcadia_FilePath* path
  ) Delete a regular file.

Parameters

A pointer to the Arcadia_Thread object.
A pointer to this Arcadia_FileSystem object.
Arcadia_FilePath* path
The path to the file.

Errors

Arcadia_Status_AccessDenied
self is a null pointer.
Arcadia_Status_ArgumentValueInvalid
self is a null pointer.
Arcadia_Status_ArgumentValueInvalid
path is a null pointer.
Arcadia_Status_AccessDenied
Access to the file was denied.
Arcadia_Status_NotFound
The file was not found.
Arcadia_Status_OperationFailed
Deletion failed.

Arcadia_FileSystem_deleteRegularFile

void
Arcadia_FileSystem_deleteRegularFile
  (
    Arcadia_Thread* thread,
    Arcadia_FileSystem* self,
    Arcadia_FilePath* path
  ) Delete a regular file.

Parameters

A pointer to the Arcadia_Thread object.
A pointer to this Arcadia_FileSystem object.
Arcadia_FilePath* path
The path to the file.

Errors

Arcadia_Status_ArgumentValueInvalid
self is a null pointer.
Arcadia_Status_ArgumentValueInvalid
path is a null pointer.
Arcadia_Status_AccessDenied
Access to the file was denied.
Arcadia_Status_NotFound
The file was not found.
Arcadia_Status_OperationFailed
The file is not a regular file, or deletion failed.

Arcadia_FileSystem_directoryFileExists

Arcadia_BooleanValue
Arcadia_FileSystem_directoryFileExists
  (
    Arcadia_Thread* thread,
    Arcadia_FileSystem* self,
    Arcadia_FilePath* path
  ) Get if a file exists and is a directory file.

Parameters

A pointer to the Arcadia_Thread object.
A pointer to this Arcadia_FileSystem object.
Arcadia_FilePath* path
The file path of the file.

Return value

Arcadia_BooleanValue_True if the file exists and is a directory file. Arcadia_BooleanValue_False otherwise.

Errors

Arcadia_Status_ArgumentValueInvalid
self is a null pointer.
Arcadia_Status_ArgumentValueInvalid
path is a null pointer.

Arcadia_FileSystem_getConfigurationDirectory

Arcadia_FilePath*
Arcadia_FileSystem_getConfigurationDirectory
  (
    Arcadia_Thread* thread,
    Arcadia_FileSystem* self
  ) Get the path to the "configuration" directory. Get the directory in which configuration files are stored. The following table lists the values for a given operating system
  • Windows: C:\Users\<Username>\AppData\Local\<Organization Name>\<Game Name>
  • Linux: <Home>\<Organization Name>\<Game Name>

Parameters

A pointer to the Arcadia_Thread object.
A pointer to this Arcadia_FileSystem object.

Return value

A pointer to the the path of the "configuration" directory.

Errors

Arcadia_Status_ArgumentValueInvalid
self is a null pointer.

Arcadia_FileSystem_getFileContents

Arcadia_ByteBuffer*
Arcadia_FileSystem_getFileContents
  (
    Arcadia_Thread* thread,
    Arcadia_FileSystem* self,
    Arcadia_FilePath* path
  ) Get the contents of a file.

Parameters

A pointer to the Arcadia_Thread object.
A pointer to this Arcadia_FileSystem object.
The file path of the file.

Return value

A pointer to a Arcadia_ByteBuffer object with the file contents.

Errors

self is a null pointer.
path is a null pointer.
Opening the file failed.

Arcadia_FileSystem_getOrCreate

Arcadia_FileSystem*
Arcadia_FileSystem_getOrCreate
  (
    Arcadia_Thread* thread
  ) Get or create the file system singleton.

Parameters

A pointer to the Arcadia_Thread object.

Errors

Arcadia_Status_AllocationFailed
An allocation failed.

Return value

A pointer to a Arcadia_FileSystem object.

Arcadia_FileSystem_getSaveDirectory

Arcadia_FilePath*
Arcadia_FileSystem_getSaveDirectory
  (
    Arcadia_Thread* thread,
    Arcadia_FileSystem* self
  ) Get the path to the "save" directory. Get the directory in which save files are stored. The following table lists the values for a given operating system
  • Windows: C:\Users\<Username>\AppData\Roaming\<Organization Name>\<Game Name>
  • Linux: <Home>\<Organization Name>\<Game Name>

Parameters

A pointer to the Arcadia_Thread object.
A pointer to this Arcadia_FileSystem object.

Return value

A pointer to the the path of the "save" directory.

Errors

Arcadia_Status_ArgumentValueInvalid
self is a null pointer.

Arcadia_FileSystem_getWorkingDirectory

Arcadia_FilePath*
Arcadia_FileSystem_getWorkingDirectory
  (
    Arcadia_Thread* thread,
    Arcadia_FileSystem* self
  ) Get the working directory of this process.

Parameters

A pointer to the Arcadia_Thread object.
A pointer to this Arcadia_FileSystem object.

Return value

A pointer to the path of the working directory.

Errors

Arcadia_Status_ArgumentValueInvalid
self is a null pointer.

Arcadia_FileSystem_regularFileExists

Arcadia_BooleanValue
Arcadia_FileSystem_regularFileExists
  (
    Arcadia_Thread* thread,
    Arcadia_FileSystem* self,
    Arcadia_FilePath* path
  ) Get if a file exists and is a regular file.

Parameters

A pointer to the Arcadia_Thread object.
A pointer to this Arcadia_FileSystem object.
Arcadia_FilePath* path
The file path of the file.

Return value

Arcadia_BooleanValue_True if the file exists and is a regular file. Arcadia_BooleanValue_False otherwise.

Errors

Arcadia_Status_ArgumentValueInvalid
self is a null pointer.
Arcadia_Status_ArgumentValueInvalid
path is a null pointer.

Arcadia_FileSystem_setFileContents

void
Arcadia_FileSystem_setFileContents
  (
    Arcadia_Thread* thread,
    Arcadia_FileSystem* self,
    Arcadia_FilePath* path,
    Arcadia_ByteBuffer* contents
  ) Set the contents of a file.

Parameters

A pointer to the Arcadia_Thread object.
A pointer to this Arcadia_FileSystem object.
Arcadia_FilePath* path
The file path of the file.
Arcadia_ByteBuffer* contents
A poiner to the Byte buffer with the file contents.

Errors

Arcadia_Status_ArgumentValueInvalid
self is a null pointer.
Arcadia_Status_ArgumentValueInvalid
path is a null pointer.
Arcadia_Status_ArgumentValueInvalid
contents is a null pointer.
Arcadia_Status_OperationFailed
Opening the file failed.

Arcadia_FileType

typedef enum Arcadia_FileType Arcadia_FileType; An enumeration of file types. The enumeration elements cannot be combined.

Elements

Arcadia_FileType_Unknown
The file type of a file is not known.
Arcadia_FileType_Regular
A file is a regular file.
Arcadia_FileType_Directory
A file is a directory file.

Arcadia_NonExistingFilePolicy

typedef enum Arcadia_NonExistingFilePolicy Arcadia_NonExistingFilePolicy; An enumeration of policies for opening a file in case of that the file does not exist. The enumeration elements cannot be combined.

Elements

Arcadia_NonExistingFilePolicy_Fail
Fail if the file does not exist.
Arcadia_NonExistingFilePolicy_Create
Create the file if it does not exist.