Functions for interacting with the calculator's file system. More...

#include <cstdint>
#include <stdint.h>
#include <stddef.h>

Include dependency graph for file.h:

Classes
struct	File_Stat

Macros
#define	constexpr

#define	cstr(x) __attribute__((null_terminated_string_arg(x)))

#define	ro(...) __attribute__((access(read_only, __VA_ARGS__)))

#define	rw(...) __attribute__((access(read_write, __VA_ARGS__)))

#define	wo(...) __attribute__((access(write_only, __VA_ARGS__)))

#define	wu __attribute__((warn_unused_result))

Typedefs
typedef uint16_t	char_const16_t

Enumerations
enum	File_Error { FILE_OK = 0 , FILE_ENOMEM = -1 , FILE_EINVAL = -2 , FILE_EDEVFAIL = -3 , FILE_EMOUNTED = -4 , FILE_EACCES = -5 , FILE_EBADFSID = -6 , FILE_ENOVOLUME = -7 , FILE_ENOPATH = -8 , FILE_EEXIST = -9 , FILE_ENAMETOOLONG = -10 , FILE_EOUTOFBOUND = -11 , FILE_EUNFORMAT = -12 , FILE_ENOSPC = -13 , FILE_ENOENT = -14 , FILE_EISDIRECTORY = -15 , FILE_ESHARE = -16 , FILE_EMFILE = -17 , FILE_EBADF = -18 , FILE_EEOF = -19 , FILE_ENOTEMPTY = -20 , FILE_ECLUSTERSIZEMISMATCH = -40 , FILE_ESYSTEM = -99 }

enum	File_Whence { FILE_SEEK_SET = 0 , FILE_SEEK_CUR = 1 , FILE_SEEK_END = 2 }

enum	File_Open { FILE_OPEN_READ = 1 << 0 , FILE_OPEN_WRITE = 1 << 1 , FILE_OPEN_CREATE = 1 << 2 , FILE_OPEN_APPEND = 1 << 4 }

Functions
struct	__attribute__ ((packed)) File_FindInfo

Variables
enum File_Error(*	File_Close )(int fd)

enum File_Error(*	File_FindClose )(int findHandle)

enum File_Error(*	File_FindFirst )(const char_const16_t path, int findHandle, char_const16_t name, struct File_FindInfo findInfoBuf) wu cstr(1) ro(1) wo(2) wo(3) wo(4)

enum File_Error(*	File_FindNext )(int findHandle, char_const16_t name, struct File_FindInfo findInfoBuf) wu wo(2) wo(3)

enum File_Error(*	File_Fstat )(int fd, struct File_Stat *buf) wu wo(2)

enum File_Error(*	File_GetAddr )(int fd, int offset, const void **addr) wu wo(3)

int(*	File_Lseek )(int fd, int offset, enum File_Whence whence) wu

enum File_Error(*	File_Mkdir )(const char *path) wu cstr(1) ro(1)

int(*	File_Open )(const char *path, int flags) wu cstr(1) ro(1)

int(*	File_Read )(int fd, void *buf, int count) wu wo(2

int() enum File_Error(	File_Remove )(const char *path) cstr(1) ro(1)

enum File_Error(*	File_Rename )(const char oldPath, const char newPath) wu cstr(1) cstr(2) ro(1) ro(2)

enum File_Error(*	File_Stat )(const char path, struct File_Stat buf) wu cstr(1) ro(1) wo(2)

int(*	File_Write )(int fd, const void *buf, int count) wu ro(2

Detailed Description

Functions for interacting with the calculator's file system.

Provides an API similar to that of Unix.

The storage which appears when the calculator is attached to a PC is found under the path \\fls0\ (remember to escape the \ in strings!).

Example: reading 256 bytes from a file called test.txt from the USB flash

int fd = File_Open("\\\\fls0\\test.txt", FILE_OPEN_READ);
if (fd < 0) {
    // An error occurred calling open
    goto exit;
}
 
uint8_t buf[256];
int ret = File_Read(fd, buf, sizeof(buf));
if (ret < 0) {
    // An error occurred calling read
    File_Close(fd);
    goto exit;
}
 
ret = File_Close(fd);
if (ret < 0) {
    // An error occurred calling close
}
 
exit:

Example: writing 16 bytes to a non-existant file called f.bin in a folder test in the USB flash

int fd = File_Open("\\\\fls0\\test\\f.bin", FILE_OPEN_WRITE | FILE_OPEN_CREATE);
if (fd < 0) {
    // An error occurred calling open
    goto exit;
}
 
uint8_t buf[] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 0xA, 0xB, 0xC, 0xD, 0xE, 0xF};
int ret = File_Write(fd, buf, sizeof(buf));
if (ret < 0) {
    // An error occurred calling write
    File_Close(fd);
    goto exit;
}
 
ret = File_Close(fd);
if (ret < 0) {
    // An error occurred calling close
}
 
exit:

Enumeration Type Documentation

◆ File_Error

enum File_Error

Errors returned by file system functions. All negative numbers.

◆ File_Open

enum File_Open

Values passed as the flags parameter to File_Open. Can be bitwise OR'd to combine effects.

Enumerator
FILE_OPEN_READ	Open the file as readable.
FILE_OPEN_WRITE	Open the file as writable.
FILE_OPEN_CREATE	Create the file, if it does not already exist.
FILE_OPEN_APPEND	Opens the file with the file offset set to the end of the file.

◆ File_Whence

enum File_Whence

Values passed as the whence parameter to File_Lseek.

Enumerator
FILE_SEEK_SET	Set the file offset to `offset`.
FILE_SEEK_CUR	Set the file offset to the current position, plus `offset` bytes.
FILE_SEEK_END	Set the file offset to the end of the file, plus `offset` bytes.

Function Documentation

◆ attribute()

struct __attribute__ ( (packed) )

Information about a file/directory, as returned from findFirst or findNext.

The type of entry which was located.

The size of the entry, in bytes. If the entry is a directory, size is zero.

Variable Documentation

◆ File_Close

enum File_Error(* File_Close) (int fd) ( int fd )

extern

Closes an open file.

Parameters

fd	The file descriptor for the open file.

Returns: 0 on success, or a negative error code on failure.

◆ File_FindClose

enum File_Error(* File_FindClose) (int findHandle) ( int findHandle )

extern

Closes a find handle.

Very, very, very bad things happen if a find handle is not closed.

Parameters

findHandle The find handle to close.

Returns: 0 on success, or a negative error code on failure.

◆ File_FindFirst

enum File_Error(* File_FindFirst) (const char_const16_t path, int findHandle, char_const16_t name, struct File_FindInfo findInfoBuf) wu cstr(1) ro(1) wo(2) wo(3) wo(4)	(	const char_const16_t *	path,
		int *	findHandle,
		char_const16_t *	name,
		struct File_FindInfo *	findInfoBuf
	)

extern

Starts a find operation, locating files matching a specific path.

Can be used to list the contents of a directory by using a wildcard. For example, passing the path L"\\fls0\\*" or L"\\fls0\\*.*" matches all files and directories on the calculator's flash (not recursive, though).

To find the next file/directory which matches the path, call File_FindNext, passing in the find handle returned by this function. Ensure the find handle is closed using File_FindClose when the find operation is finished. Bad things happen if the handle is not closed.

Parameters

[in]	path	The path to search. May contain wildcards.
[out]	findHandle	The find handle created. Must be closed when the find operation is finished.
[out]	name	The name of the file/directory found.
[out]	findInfoBuf	Information about the found file.

Returns: 0 on success, or a negative error code on failure.

◆ File_FindNext

enum File_Error(* File_FindNext) (int findHandle, char_const16_t name, struct File_FindInfo findInfoBuf) wu wo(2) wo(3)	(	int	findHandle,
		char_const16_t *	name,
		struct File_FindInfo *	findInfoBuf
	)

extern

Returns information about the next matching file/directory in a find operation.

Parameters

	findHandle	The find handle returned from File_FindFirst.
[out]	name	The name of the file/directory found.
[out]	findInfoBuf	Information about the found file.

Returns: 0 on success, or a negative error code on failure.

◆ File_Fstat

enum File_Error(* File_Fstat) (int fd, struct File_Stat *buf) wu wo(2)	(	int	fd,
		struct File_Stat *	buf
	)

extern

Retrieves information about an open file.

Parameters

	fd	The file descriptor of an open file to retrieve the information of.
[out]	buf	The retrieved information about the file.

Returns: 0 on success, or a negative error code on failure.

◆ File_GetAddr

enum File_Error(* File_GetAddr) (int fd, int offset, const void **addr) wu wo(3)	(	int	fd,
		int	offset,
		const void **	addr
	)

extern

Retrieves the memory address of a file.

If the file is empty or the offset would point outside of the file, FILE_EINVAL is returned.

Parameters

	fd	The file descriptor of an open file.
	offset	An offset to apply to the pointer to the file's data.
[out]	addr	The address of the file's data.

Returns: 0 on success, or a negative error code on failure.

◆ File_Lseek

int(* File_Lseek) (int fd, int offset, enum File_Whence whence) wu	(	int	fd,
		int	offset,
		enum File_Whence	whence
	)

extern

Repositions the file offset of the file descriptor. The new position depends on the value of both offset and whence. See lseek_whence_values.

Parameters

fd	The file descriptor of an open file to change the file offset of.
offset	The new offset, relative to some point.
whence	Where `offset` is relative to.

Returns: The new file offset on success, or a negative error code on failure.

◆ File_Mkdir

enum File_Error(* File_Mkdir) (const char *path) wu cstr(1) ro(1) ( const char * path )

extern

Creates a directory.

Parameters

[in] path The path to the directory to be created.

Returns: 0 on success, or a negative error code on failure.

◆ File_Open

int(* File_Open) (const char *path, int flags) wu cstr(1) ro(1)	(	const char *	path,
		int	flags
	)

extern

Opens a file on the file system.

The argument flags is fed a bitwise OR'd combination of flags. See open_flags_values.

Parameters

[in]	path	The path to the file to open.
	flags	A bitfield describing the mode in which to open the file.

Returns: A file descriptor on success, or a negative error code on failure.

◆ File_Read

int(* File_Read) (int fd, void *buf, int count) wu wo(2	(	int	fd,
		void *	buf,
		int	count
	)

extern

Reads up to count bytes from a file, and stores them in buf.

If count bytes cannot be read from the file, as many bytes as possible are read (i.e. between 0 and count - 1 bytes are read and stored in buf).

Parameters

	fd	The file descriptor of an open file to read from.
[out]	buf	A buffer to place the read bytes into.
	count	The maximum number of bytes to read.

Returns: The number of bytes read on success, or a negative error code on failure.

◆ File_Remove

int(*) enum File_Error(* File_Remove) (const char *path) cstr(1) ro(1) ( const char * path )

extern

Deletes a file or directory.

Parameters

[in] path The path to the file or directory to be deleted.

Returns: 0 on success, or a negative error code on failure.

◆ File_Rename

enum File_Error(* File_Rename) (const char oldPath, const char newPath) wu cstr(1) cstr(2) ro(1) ro(2)	(	const char *	oldPath,
		const char *	newPath
	)

extern

Renames a file or directory.

Parameters

[in]	oldPath	The path to the file or directory to be renamed.
[in]	newPath	The path to the new name for the file or directory.

Returns: 0 on success, or a negative error code on failure.

◆ File_Stat

enum File_Error(* File_Stat) (const char path, struct File_Stat buf) wu cstr(1) ro(1) wo(2)	(	const char *	path,
		struct File_Stat *	buf
	)

extern

Retrieves information about a file.

Parameters

[in]	path	The path to the file to retrieve the information of.
[out]	buf	The retrieved information about the file.

Returns: 0 on success, or a negative error code on failure.

◆ File_Write

int(* File_Write) (int fd, const void *buf, int count) wu ro(2	(	int	fd,
		const void *	buf,
		int	count
	)

extern

Writes count bytes from buf to a file.

Parameters

	fd	The file descriptor of an open file to write to.
[in]	buf	A buffer of bytes to write to the file.
	count	The number of bytes from `buf` to write to the file.

Returns: The number of bytes written on success, or a negative error code on failure.

Classes

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ File_Error

◆ File_Open

◆ File_Whence

Function Documentation

◆ __attribute__()

Variable Documentation

◆ File_Close

◆ File_FindClose

◆ File_FindFirst

◆ File_FindNext

◆ File_Fstat

◆ File_GetAddr

◆ File_Lseek

◆ File_Mkdir

◆ File_Open

◆ File_Read

◆ File_Remove

◆ File_Rename

◆ File_Stat

◆ File_Write

◆ attribute()