file.hpp File Reference

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

#include <stdint.h>

Include dependency graph for file.hpp:

Go to the source code of this file.

Classes
struct	File_Stat
struct	File_FindInfo

Functions
uint16_t constexpr	File_StatDateYear (uint16_t date)
uint16_t constexpr	File_StatDateMonth (uint16_t date)
uint16_t constexpr	File_StatDateDay (uint16_t date)
uint16_t constexpr	File_StatTimeHour (uint16_t time)
uint16_t constexpr	File_StatTimeMinute (uint16_t time)
uint16_t constexpr	File_StatTimeSecond (uint16_t time)
int	File_Close (int fd)
int	File_FindClose (int findHandle)
int	File_FindFirst (const wchar_t *path, int *findHandle, wchar_t *name, struct File_FindInfo *findInfoBuf)
int	File_FindNext (int findHandle, wchar_t *name, struct File_FindInfo *findInfoBuf)
int	File_Fstat (int fd, struct File_Stat *buf)
int	File_GetAddr (int fd, int offset, const void **addr)
int	File_Lseek (int fd, int offset, int whence)
int	File_Mkdir (const char *path)
int	File_Open (const char *path, int flags)
int	File_Read (int fd, void *buf, int count)
int	File_Remove (const char *path)
int	File_Rename (const char *oldPath, const char *newPath)
int	File_Stat (const char *path, struct File_Stat *buf)
int	File_Write (int fd, const void *buf, int count)

Variables
const int	FILE_SEEK_SET = 0
	Set the file offset to offset.
const int	FILE_SEEK_CUR = 1
	Set the file offset to the current position, plus offset bytes.
const int	FILE_SEEK_END = 2
	Set the file offset to the end of the file, plus offset bytes.
const int	FILE_OPEN_READ = 1 << 0
	Open the file as readable.
const int	FILE_OPEN_WRITE = 1 << 1
	Open the file as writable.
const int	FILE_OPEN_CREATE = 1 << 2
	Create the file, if it does not already exist.
const int	FILE_OPEN_APPEND = 1 << 4
	Opens the file with the file offset set to the end of the file.
Errors
Errors returned by file system functions. All negative numbers.
const int	FILE_ENOMEM = -1
const int	FILE_EINVAL = -2
const int	FILE_EDEVFAIL = -3
const int	FILE_EMOUNTED = -4
const int	FILE_EACCES = -5
const int	FILE_EBADFSID = -6
const int	FILE_ENOVOLUME = -7
const int	FILE_ENOPATH = -8
const int	FILE_EEXIST = -9
const int	FILE_ENAMETOOLONG = -10
const int	FILE_EOUTOFBOUND = -11
const int	FILE_EUNFORMAT = -12
const int	FILE_ENOSPC = -13
const int	FILE_ENOENT = -14
const int	FILE_EISDIRECTORY = -15
const int	FILE_ESHARE = -16
const int	FILE_EMFILE = -17
const int	FILE_EBADF = -18
const int	FILE_EEOF = -19
const int	FILE_ENOTEMPTY = -20
const int	FILE_ECLUSTERSIZEMISMATCH = -40
const int	FILE_ESYSTEM = -99

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:

Function Documentation

File_Close()

int File_Close

(

int

fd

)

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()

int File_FindClose

(

int

findHandle

)

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()

int File_FindFirst	(	const wchar_t *	path,
		int *	findHandle,
		wchar_t *	name,
		struct File_FindInfo *	findInfoBuf
	)

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()

int File_FindNext	(	int	findHandle,
		wchar_t *	name,
		struct File_FindInfo *	findInfoBuf
	)

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()

int File_Fstat	(	int	fd,
		struct File_Stat *	buf
	)

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()

int File_GetAddr	(	int	fd,
		int	offset,
		const void **	addr
	)

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,
		int	whence
	)

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()

int File_Mkdir

(

const char *

path

)

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
	)

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
	)

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 File_Remove

(

const char *

path

)

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()

int File_Rename	(	const char *	oldPath,
		const char *	newPath
	)

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()

int File_Stat	(	const char *	path,
		struct File_Stat *	buf
	)

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_StatDateDay()

uint16_t constexpr File_StatDateDay ( uint16_t  date )

constexpr

Retrieves the day from a struct File_stat date field.

Parameters

date	The date field from a struct File_stat.

Returns

The day encoded in the date field.

File_StatDateMonth()

uint16_t constexpr File_StatDateMonth ( uint16_t  date )

constexpr

Retrieves the month from a struct File_Stat date field.

Parameters

date	The date field from a struct File_Stat.

Returns

The month encoded in the date field.

File_StatDateYear()

uint16_t constexpr File_StatDateYear ( uint16_t  date )

constexpr

Retrieves the year from a struct File_Stat date field.

Parameters

date	The date field from a struct File_Stat.

Returns

The year encoded in the date field.

File_StatTimeHour()

uint16_t constexpr File_StatTimeHour ( uint16_t  time )

constexpr

Retrieves the hour from a struct File_Stat time field.

Parameters

time	The time field from a struct File_Stat.

Returns

The hour encoded in the time field.

File_StatTimeMinute()

uint16_t constexpr File_StatTimeMinute ( uint16_t  time )

constexpr

Retrieves the minute from a struct File_Stat time field.

Parameters

time	The time field from a struct File_Stat.

Returns

The minute encoded in the time field.

File_StatTimeSecond()

uint16_t constexpr File_StatTimeSecond ( uint16_t  time )

constexpr

Retrieves the second from a struct File_Stat time field.

Has a maximum resolution of 2 seconds.

Parameters

time	The time field from a struct File_Stat.

Returns

The second encoded in the time field.

File_Write()

int File_Write	(	int	fd,
		const void *	buf,
		int	count
	)

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.