fileioc.h

#include <fileioc.h>

The fileioc library provides access to OS variables such as AppVars, Programs, Lists, and Strings.

AppVars are special types of variables that can be used to store any arbitrary data, and are utilized by the CE toolchain to provide data storage beyond what can be compiled into a program. AppVars may store things like save states, sprites, and user configurations. Because the program context is destroyed when a program returns to the OS, AppVars can be used to store data between program launches.

The OS stores variables in either RAM or archive (aka flash) memory. RAM memory is volatile and is cleared whenever the calculator is reset, whereas archive memory provides a more permanent storage for variables. However, variables can only be written to while in RAM as the calculator’s security measures do not provide a way to directly write to the archive. The function ti_SetArchiveStatus can be used to move a variable between the archive and RAM.

The function ti_Open and ti_OpenVar can be used to access AppVars and other OS variables respectively. They return an opaque handle value that is passed to the other functions available in the library.

API Documentation

Author

Matt “MateoConLechuga” Waltz

Defines

ti_MallocReal()

Allocate a real_t variable on the C heap using malloc().

Does not modify OS storage. The allocated variable should be free’d with the free() function when you are done using it.

Returns

Pointer to real_t allocated variable.

ti_MallocCplx()

Allocate a cplx_t variable on the C heap using malloc().

Does not modify OS storage. The allocated variable should be free’d with the free() function when you are done using it.

Returns

Pointer to cplx_t allocated variable.

ti_MallocString(len)

Allocate a string_t variable on the C heap using malloc().

Does not modify OS storage. The allocated variable should be free’d with the free() function when you are done using it.

Parameters

  • len – [in] Length of string to allocate in tokens/characters.

Returns

Pointer to string_t allocated variable.

ti_MallocList(dim)

Allocate a list_t variable on the C heap using malloc().

Does not modify OS storage. The allocated variable should be free’d with the free() function when you are done using it.

Parameters

  • dim – [in] Dimension of list.

Returns

Pointer to list_t allocated variable.

ti_MallocMatrix(rows, cols)

Allocate a matrix_t variable on the C heap using malloc().

Does not modify OS storage. The allocated variable should be free’d with the free() function when you are done using it.

Parameters

  • rows – [in] Number of rows in matrix.

  • cols – [in] Number of columns in matrix.

Returns

Pointer to matrix_t allocated variable.

ti_MallocCplxList(dim)

Allocate a cplx_list_t variable on the C heap using malloc().

Does not modify OS storage. The allocated variable should be free’d with the free() function when you are done using it.

Parameters

  • dim – [in] Dimension of list.

Returns

Pointer to cplx_list_t allocated variable.

ti_MallocEqu(len)

Allocate a equ_t variable on the C heap using malloc().

Does not modify OS storage. The allocated variable should be free’d with the free() function when you are done using it.

Parameters

  • len – [in] Length of equation to allocate in tokens/characters.

Returns

Pointer to equ_t allocated variable.

Functions

uint8_t ti_Open(const char *name, const char *mode)

Opens an AppVar for reading, writing, and/or appending.

AppVars may be stored in either the archive (aka flash memory), or in RAM. Depending on the mode used to open the AppVar it may be moved from archive memory into RAM.

mode

Description

”r”

Read mode. If the AppVar does not exist 0 is returned. The AppVar is not moved from its storage location.

”w”

Write mode. Deletes any existing AppVar and creates the AppVar in RAM.

”a”

Append mode. The AppVar is created if it does not exist. If the AppVar is stored in the archive it is moved to RAM.

”r+”

Read/Write mode. If the AppVar does not exist 0 is returned. If the AppVar is stored in the archive it is moved to RAM.

”w+”

Write/Read mode. Deletes any existing AppVar and creates the AppVar in RAM.

”a+”

Append/Read mode. The AppVar is created if it does not exist. If the AppVar is stored in the archive it is moved to RAM.

Parameters

  • name – [in] Name of AppVar to open.

  • mode – [in] Documented in the above table.

Returns

AppVar variable handle, or 0 (zero) on error.

uint8_t ti_OpenVar(const char *name, const char *mode, uint8_t type)

Opens a variable for reading, writing, and/or appending.

Variables may be stored in either the archive (aka flash memory), or in RAM. Depending on the mode used to open the variable it may be moved from archive memory into RAM.

mode

Description

”r”

Read mode. If the variable does not exist 0 is returned. The variable is not moved from its storage location.

”w”

Write mode. Deletes any existing variable and creates the variable in RAM.

”a”

Append mode. The variable is created if it does not exist. If the variable is stored in the archive it is moved to RAM.

”r+”

Read/Write mode. If the variable does not exist 0 is returned. If the variable is stored in the archive it is moved to RAM.

”w+”

Write/Read mode. Deletes any existing variable and creates the variable in RAM.

”a+”

Append/Read mode. The variable is created if it does not exist. If the variable is stored in the archive it is moved to RAM.

Parameters

  • name – [in] Name of variable to open.

  • mode – [in] Documented in the above table.

  • type – [in] Variable type.

Returns

Variable handle, or 0 (zero) on error.

int ti_Close(uint8_t handle)

Closes an open AppVar/variable handle.

This must be performed for every ti_Open or ti_OpenVar call.

Parameters

handle – [in] AppVar/variable handle.

Returns

0 (zero) on error.

char *ti_Detect(void **vat_ptr, const char *detect_string)

Locates AppVars stored in archive and RAM.

This function searches for AppVars whose data section begins with a specific string. The null terminator of the string is not included in the search.

vat_ptr should be set to NULL to begin a search, and is updated with each call.

char *var_name;
void *vat_ptr = NULL;

while ((var_name = ti_Detect(&vat_ptr, "my_data")))
{
    // do something with var_name or vat_ptr
}

Note

If the return value is NULL, there are no more variables to find.

Parameters

  • vat_ptr – [in] Current offset in the VAT.

  • detect_string – [in] String to search for (NULL to search for all).

Returns

The AppVar name. This should be duplicated to another buffer as subsequent calls of this function change the name stored at the returned pointer’s address.

char *ti_DetectVar(void **vat_ptr, const char *detect_string, uint8_t var_type)

Locates variables stored in archive and RAM.

This function searches for variables whose data section begins with a specific string. The null terminator of the string is not included in the search.

vat_ptr should be set to NULL to begin a search, and is updated with each call.

char *var_name;
void *vat_ptr = NULL;

while ((var_name = ti_DetectVar(&vat_ptr, "my_data", OS_TYPE_PRGM)))
{
    // do something with var_name or vat_ptr
}

Note

If the return value is NULL, there are no more variables to find.

Parameters

  • vat_ptr – [inout] Current offset in the VAT.

  • detect_string – [in] String to search for (NULL to search for all).

  • var_type – [in] Type of variable to detect.

Returns

The variable name. This should be duplicated to another buffer as subsequent calls of this function change the name stored at the returned pointer’s address.

char *ti_DetectAny(void **vat_ptr, const char *detect_string, uint8_t *var_type)

Locates any variables stored in archive and RAM.

This function searches for variables whose data section begins with a specific string. The null terminator of the string is not included in the search.

vat_ptr should be set to NULL to begin a search, and is updated with each call.

uint8_t var_type;
char *var_name;
void *vat_ptr = NULL;

while ((var_name = ti_DetectAny(&vat_ptr, "my_data", &var_type)))
{
    if (var_type == OS_TYPE_PRGM || var_type == OS_TYPE_PROT_PRGM)
    {
        // do something with var_name or vat_ptr
    }
}

Note

If the return value is NULL, there are no more variables to find.

Parameters

  • vat_ptr – [inout] Current offset in the VAT.

  • detect_string – [in] String to search for (NULL to search for all).

  • var_type – [out] Type of variable found.

Returns

The variable name. This should be duplicated to another buffer as subsequent calls of this function change the name stored at the returned pointer’s address.

size_t ti_Write(const void *data, size_t size, size_t count, uint8_t handle)

Writes data to an AppVar/variable handle.

Parameters

  • data – [in] Pointer to data element(s).

  • size – [in] Size (in bytes) of a single data element.

  • count – [in] Number of data elements to write.

  • handle – [in] AppVar/variable handle.

Returns

Number of data elements written; equals count on success.

size_t ti_Read(void *data, size_t size, size_t count, uint8_t handle)

Reads data from an AppVar/variable handle.

Parameters

  • data – [out] Pointer to data element(s).

  • size – [in] Size (in bytes) of a single data element.

  • count – [in] Number of data elements to read.

  • handle – [in] AppVar/variable handle.

Returns

Number of data elements written; equals count on success.

int ti_PutC(char ch, uint8_t handle)

Writes a character to an AppVar/variable handle.

Parameters

  • ch – [in] Character to write.

  • handle – [in] AppVar/variable handle.

Returns

EOF on error, or ch.

int ti_GetC(uint8_t handle)

Reads a character from an AppVar/variable handle.

Parameters

handle – [in] AppVar/variable handle.

Returns

EOF on error, or a valid character.

int ti_Seek(int offset, unsigned int origin, uint8_t handle)

Seeks to an offset in the file.

origin

Description

SEEK_SET

Seek from beginning of AppVar/variable.

SEEK_CUR

Seek from current AppVar/variable offset.

SEEK_END

Seek from end of AppVar/variable.

Parameters

  • offset – [in] Number of bytes to offest from (can be negative).

  • origin – [in] Documented in the above table.

  • handle – [in] AppVar/variable handle.

Returns

EOF on failure.

int ti_Rewind(uint8_t handle)

Seeks to the start of an AppVar/variable’s data.

Functionally equivalent to ti_Seek(0, SEEK_SET, handle)

Parameters

handle – [in] AppVar/variable handle.

Returns

EOF on failure.

uint16_t ti_Tell(uint8_t handle)

Gets the current data offset from the start of an AppVar/variable.

Parameters

handle – [in] AppVar/variable handle.

Returns

The current data offset from the start of the AppVar/variable.

uint16_t ti_GetSize(uint8_t handle)

Gets the size of an AppVar/variable.

Parameters

handle – [in] AppVar/variable handle.

Returns

The size of the AppVar/variable.

int ti_Resize(size_t size, uint8_t handle)

Resizes an AppVar/variable.

Warning

This function does not maintain the data already stored in the AppVar/variable when shrinking/expanding, and effectively corrupts the contents.

Parameters

  • handle – [in] AppVar/variable handle.

  • size – [in] New AppVar/variable size.

Returns

Resized size on success, 0 on failure, or -1 if the AppVar/variable cannot be opened.

int ti_IsArchived(uint8_t handle)

Checks if an AppVar/variable is stored in archive memory.

Parameters

handle – [in] AppVar/variable handle.

Returns

0 if the AppVar/variable is not in the archive.

int ti_SetArchiveStatus(bool archive, uint8_t handle)

Moves an AppVar/variable between archive or RAM storage.

archive

Description

true

Store AppVar/variable in archive.

false

Store AppVar/variable in RAM.

Warning

Archiving a variable can cause a garbage collection cycle. You should use ti_SetGCBehavior to catch this event.

Parameters

  • archive – [in] Documented in the above table.

  • handle – [in] AppVar/variable handle.

Returns

0 on failure.

int ti_Delete(const char *name)

Deletes an AppVar.

Parameters

name – [in] AppVar name.

Returns

0 on failure.

int ti_DeleteVar(const char *name, uint8_t type)

Deletes a variable.

Parameters

  • name – [in] Variable name.

  • type – [in] Variable type.

Returns

0 on failure.

char *ti_GetTokenString(void **read_pointer, uint8_t *token_len, unsigned int *str_len)

Gets the string used for displaying a TI token.

The TI calculators encode programs and other variables in “tokens”, which are either 1 or 2 bytes in length. For example, the token 0x21 corresponds to the string mean( in TI-BASIC programs. This allows program size to be reduced as the whole string is not stored - but requires additional decoding in order to resolve the token’s string representation.

Note

read_pointer is automatically updated to point to the next token, incremented by the value of token_len.

Parameters

  • read_pointer – [inout] Address of pointer to data to read.

  • token_len – [out] Pointer to variable to hold length of the token, used for determining the next read location (Can be NULL if unused).

  • str_len – [out] Pointer to variable to hold length of resulting string (Can be NULL if unused). The returned string is static, and should be copied to another buffer as needed if it needs to be preserved across function calls.

Returns

A pointer to a null-terminated string used for displaying a TI token.

void *ti_GetDataPtr(uint8_t handle)

Gets a direct data pointer to the current offset in an AppVar/variable.

This may be used for direct reading/writing without the need for an extra copy. It is easily prone to memory corruption if not used correctly, so use at your own risk.

Note

If the AppVar is in RAM, the direct pointer can be used to read/modify its contents directly, with the caveat that the AppVar must be large enough to consume any writes. If the AppVar is in the archive, direct reading is possible but writes will lead to a system reset.

Warning

This function is potentially unsafe to use as variables may be shifted around in memory, causing this pointer to become invalid and potentially corrupt memory. Avoid creating, deleting, resizing, or changing the storage location any variables while this pointer is being actively used.

Parameters

handle – [in] AppVar/variable handle.

Returns

Pointer to AppVar/variable data.

void *ti_GetVATPtr(uint8_t handle)

Gets a pointer to the VAT entry of an AppVar/variable.

Note

If the variable is in RAM, the direct pointer can be used to read/modify its contents directly, with the caveat that the AppVar must be large enough to consume any writes. If the AppVar is in the archive, direct reading is possible but writes will lead to a system reset.

Warning

This function is potentially unsafe to use as variables may be shifted around in memory, causing this pointer to become invalid and potentially corrupt memory. Avoid creating, deleting, resizing, or changing the storage location any variables while this pointer is being actively used.

Parameters

handle – [in] AppVar/variable handle.

Returns

VAT location of the variable.

void ti_GetName(char *name, uint8_t handle)

Gets the AppVar/variable name of an already opened handle.

Parameters

  • name – [in] Buffer to store name, must be at least 10 bytes in sizew.

  • handle – [in] AppVar/variable handle.

uint8_t ti_Rename(const char *old_name, const char *new_name)

Renames an AppVar.

Warning

It is hazardous to rename an open AppVar. Close the AppVar before renaming.

Parameters

  • old_name – [in] Old name of AppVar.

  • new_name – [in] New name of AppVar.

Returns

0 if success, 1 if AppVar already exists, 2 any other error occurs.

uint8_t ti_RenameVar(const char *old_name, const char *new_name, uint8_t type)

Renames a variable.

Warning

It is hazardous to rename an open variable. Close the variable before renaming.

Parameters

  • old_name – [in] Old name of variable.

  • new_name – [in] New name of variable.

  • type – [in] Type of variable.

Returns

0 if success, 1 if variable already exists, 2 any other error occurs.

uint8_t ti_SetVar(uint8_t type, const char *name, const void *data)

Stores data or values to an OS variable.

Parameters

  • type – [in] Variable type.

  • name – [in] Variable name.

  • data – [in] Data to set variable to.

Returns

0 if success, otherwise TI OS Error Code.

uint8_t ti_StoVar(uint8_t type_to, const char *to, uint8_t type_from, const char *from)

Stores an OS variable to another variable.

Parameters

  • type_to – [in] Variable type to store data to.

  • to – [in] Variable name to store data to.

  • type_from – [in] Variable type to get data from.

  • from – [in] Variable name to get data from.

Returns

0 if success, otherwise TI OS Error Code.

uint8_t ti_RclVar(uint8_t type, const char *name, void **data)

Recalls a OS variable.

Parameters

  • type – [in] Variable type.

  • name – [in] Variable name.

  • data – [out] Address of pointer to variable structure.

Returns

0 if success, otherwise TI OS Error Code.

bool ti_ArchiveHasRoom(uint24_t num_bytes)

Checks to see if there is room in the archive for storing num_bytes, without needing to execute a Garbage Collect.

Parameters

num_bytes – [in] Number of bytes to be stored to the archive.

Returns

true if the bytes can be stored to the archive without triggering a Garbage Collect.

bool ti_ArchiveHasRoomVar(uint8_t handle)

Checks to see if there is room in the archive for storing an AppVar/variable, without needing to execute a Garbage Collect.

Parameters

handle – [in] AppVar/variable handle.

Returns

true if archiving the variable will trigger a Garbage Collect.

void ti_SetGCBehavior(void (*before)(void), void (*after)(void))

Set routines to run before and after a garbage collect would be triggered.

A garbage collect is used to free up space in archive memory by reorganizing archive variable storage and removing variables marked for deletion. The OS is required to request the user if they want to perform the operation, and this request may be triggered any time a variable is moved to archive memory. This function is used to set up callbacks that are triggered when this event occurs.

The OS prompt requires the LCD to be in the standard 16-bit color mode, so if graphx or custom LCD behavior is being used gfx_End should be used to restore the OS to its default state in the routine run before garbage collection.

In the after garbage collection rotuine, the LCD state can be restored (using gfx_Begin or similar as appropriate), as well as potentially reloading cached variable pointers created with ti_GetDataPtr.

Parameters

  • before – [in] Routine to run before a garbage collect. NULL sets it to do nothing.

  • after – [in] Routine to run following a garbage collect. NULL sets it to do nothing.