Detailed Description

Module which contains operating system independent file I/O.

Functions
gBool	gfileExists (const char *fname)
	Check if file exists. More...

gBool	gfileDelete (const char *fname)
	Delete file. More...

gFileSize	gfileGetFilesize (const char *fname)
	Get the size of a file. More...

gBool	gfileRename (const char oldname, const char newname)
	Rename file. More...

GFILE *	gfileOpen (const char fname, const char mode)
	Open file. More...

void	gfileClose (GFILE *f)
	Close file. More...

gMemSize	gfileRead (GFILE f, void buf, gMemSize len)
	Read from file. More...

gMemSize	gfileWrite (GFILE f, const void buf, gMemSize len)
	Write to file. More...

gFileSize	gfileGetPos (GFILE *f)
	Get the current position of the read/write cursor. More...

gBool	gfileSetPos (GFILE *f, gFileSize pos)
	Set the position of the read/write cursor. More...

gFileSize	gfileGetSize (GFILE *f)
	Get the size of file. More...

gBool	gfileEOF (GFILE *f)
	Check for EOF. More...

gBool	gfileMount (char fs, const char *drive)
	Mount a logical drive (aka partition) More...

gBool	gfileUnmount (char fs, const char *drive)
	Unmount a logical drive (aka partition) More...

gBool	gfileSync (GFILE *f)
	Syncs the file object (flushes the buffer) More...

gfileList *	gfileOpenFileList (char fs, const char *path, gBool dirs)
	Open a file list. More...

const char *	gfileReadFileList (gfileList *pfl)
	Get the next file in a file list. More...

void	gfileCloseFileList (gfileList *pfl)
	Close a file list. More...

GFILE *	gfileOpenChibiOSFileStream (void FileStreamPtr, const char mode)
	Open file from a ChibiOS FileStream. More...

GFILE *	gfileOpenMemory (void memptr, const char mode)
	Open file from a memory pointer. More...

GFILE *	gfileOpenString (char str, const char mode)
	Open file from a null terminated C string. More...

GFILE Functionality to be included
#define	GFILE_NEED_NOAUTOMOUNT GFXOFF
	Should the filesystem not be mounted automatically. More...

#define	GFILE_NEED_NOAUTOSYNC GFXOFF
	Should the filesystem be synced automatically. More...

#define	GFILE_NEED_PRINTG GFXOFF
	Include printg, fprintg etc functions. More...

#define	GFILE_NEED_SCANG GFXOFF
	Include scang, fscang etc functions. More...

#define	GFILE_NEED_STRINGS GFXOFF
	Include the string based file functions. More...

#define	GFILE_NEED_STDIO GFXOFF
	Map many stdio functions to their GFILE equivalent. More...

#define	GFILE_NEED_USERFS GFXOFF
	Include the USER file system. More...

#define	GFILE_NEED_ROMFS GFXOFF
	Include the ROM file system. More...

#define	GFILE_NEED_RAMFS GFXOFF
	Include the RAM file system. More...

#define	GFILE_NEED_FATFS GFXOFF
	Include the FAT file system driver based on the FATFS library. More...

#define	GFILE_NEED_PETITFS GFXOFF
	Include the FAT file system driver based on the PETITFS library. More...

#define	GFILE_NEED_NATIVEFS GFXOFF
	Include the operating system's native file system. More...

#define	GFILE_NEED_CHIBIOSFS GFXOFF
	Include ChibiOS BaseFileStream support. More...

#define	GFILE_NEED_MEMFS GFXOFF
	Include raw memory pointer support. More...

#define	GFILE_NEED_FILELISTS GFXOFF
	Include support for file list functions. More...

GFILE Optional Parameters
#define	GFILE_ALLOW_FLOATS GFXOFF
	Add floating point support to printg/scang etc. More...

#define	GFILE_ALLOW_DEVICESPECIFIC GFXOFF
	Can the device be specified as part of the file name. More...

#define	GFILE_MAX_GFILES 3
	The maximum number of open files. More...

#define	GFILE_FATFS_EXTERNAL_LIB GFXOFF
	TUse an external FATFS library instead of the uGFX inbuilt one. More...

#define	GFILE_PETITFS_EXTERNAL_LIB GFXOFF
	TUse an external PETITFS library instead of the uGFX inbuilt one. More...

Typedefs
typedef struct GFILE	GFILE
	A file pointer. More...

Function Documentation

◆ gfileClose()

void gfileClose ( GFILE * f )

Close file.

Closes a file after is has been opened using gfileOpen()

Parameters

[in] f The file

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gfileCloseFileList()

void gfileCloseFileList ( gfileList * pfl )

Close a file list.

Parameters

[in] pfl Pointer to a file list returned by gfileOpenFileList()

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gfileDelete()

gBool gfileDelete ( const char * fname )

Delete file.

Parameters

[in] fname The file name

Returns: gTrue on success, gFalse otherwise

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gfileEOF()

gBool gfileEOF ( GFILE * f )

Check for EOF.

Checks if the cursor is at the end of the file

Parameters

[in] f The file

Returns: gTrue if EOF, gFalse otherwise

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gfileExists()

gBool gfileExists ( const char * fname )

Check if file exists.

Parameters

[in] fname The file name

Returns: gTrue if file exists, gFalse otherwise

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gfileGetFilesize()

gFileSize gfileGetFilesize ( const char * fname )

Get the size of a file.

Note: Please use gfileGetSize() if the file is opened

Parameters

[in] fname The file name

Returns: File size on success, (gFileSize)-1 on error

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gfileGetPos()

gFileSize gfileGetPos ( GFILE * f )

Get the current position of the read/write cursor.

Parameters

[in] f The file

Returns: The current position in the file

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gfileGetSize()

gFileSize gfileGetSize ( GFILE * f )

Get the size of file.

Note: Please use gfileGetFilesize() if the file is not opened

Parameters

[in] f The file

Returns: The size of the file

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gfileMount()

gBool gfileMount	(	char	fs,
		const char *	drive
	)

Mount a logical drive (aka partition)

Not supported by every file system

Currently just one drive at one is supported.

Parameters

[in]	fs	The file system (F for FatFS)
[in]	drive	The logical drive prefix

Returns: gTrue on success, gFalse otherwise

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gfileOpen()

GFILE* gfileOpen	(	const char *	fname,
		const char *	mode
	)

Open file.

A file must be opened before it can be accessed

The resulting GFILE will be used for all functions that access the file.

Parameters

[in]	fname	The file name
[in]	mode	The mode.

Returns: Valid GFILE on success, 0 otherwise

Note

The modes follow the c library fopen() standard. The valid modes are:

r - Open for read, the file must exist
w - Open for write, the file is truncated if it exists
wx - Open for write, the file must not exist
a - Open for append, the file is truncated if it exists
ax - Open for append, the file must not exists

The following flags can also be added to the above modes:

+ - Open for both read and write
b - Open as a binary file rather than a text file

Not all file-systems support all modes. For example, write is not available with the ROM file-system. Similarly few platforms distinguish between binary and text files.

Even though binary vs. text is relevant only for a small number of platforms the "b" flag should always be specified for binary files such as images. This ensures portability to other platforms. The extra flag will be ignored on platforms where it is not relevant.

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gfileOpenChibiOSFileStream()

GFILE* gfileOpenChibiOSFileStream	(	void *	FileStreamPtr,
		const char *	mode
	)

Open file from a ChibiOS FileStream.

Parameters

[in]	FileStreamPtr	The BaseFileStream (ChibiOS V2) or FileStream (ChibiOS V3) to open as a GFILE
[in]	mode	The mode.

Returns: Valid GFILE on success, 0 otherwise

Note: The modes are the same modes as in gfileOpen(). The open mode is NOT compared against the FileStream capabilities.; Supported operations are: read, write, getpos, setpos, eof and getsize

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gfileOpenFileList()

gfileList* gfileOpenFileList	(	char	fs,
		const char *	path,
		gBool	dirs
	)

Open a file list.

Parameters

[in]	fs	The file system (F for FatFS)
[in]	path	Path information to pass to the file system
[in]	dirs	Pass gTrue to get directories only, gFalse to get files only

Returns: A pointer to a file list on success, NULL otherwise

Note: The path parameter is handled in a file-system specific way. It could be treated as a directory name, it may be treated as a file pattern, or it may be ignored. Passing NULL will always return the full list of files in at least the top level directory.; For file systems that do not support directories, passing gTrue for dirs will return an error.; You must call gfileCloseFileList() when you have finished with the file list in order to free resources.

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gfileOpenMemory()

GFILE* gfileOpenMemory	(	void *	memptr,
		const char *	mode
	)

Open file from a memory pointer.

Parameters

[in]	memptr	The pointer to the memory
[in]	mode	The mode.

Returns: Valid GFILE on success, 0 otherwise

Note: The modes are the same modes as in gfileOpen(). Note there is no concept of file-size. Be careful not to overwrite other memory or to read from inaccessible sections of memory.; Supported operations are: read, write, getpos, setpos

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gfileOpenString()

GFILE* gfileOpenString	(	char *	str,
		const char *	mode
	)

Open file from a null terminated C string.

Parameters

[in]	str	The pointer to the string or string buffer
[in]	mode	The mode

Returns: Valid GFILE on success, 0 otherwise

Note: The modes are the same modes as in gfileOpen(). Note there is no concept of file-size. Be careful not to overwrite other memory or to read from inaccessible sections of memory.; Reading will return EOF when the NULL character is reached.; Writing will always place a NULL in the next character effectively terminating the string at the character just written.; Supported operations are: read, write, append, getpos, setpos; Be careful with setpos and getpos. They do not check for the end of the string.; Reading and Writing will read/write a maximum of one character at a time.

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gfileRead()

gMemSize gfileRead	(	GFILE *	f,
		void *	buf,
		gMemSize	len
	)

Read from file.

Reads a given amount of bytes from the file

The read/write cursor will not be reset when calling this function

Parameters

[in]	f	The file
[out]	buf	The buffer in which to save the content that has been read from the file
[in]	len	Amount of bytes to read

Returns: Amount of bytes read

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gfileReadFileList()

const char* gfileReadFileList ( gfileList * pfl )

Get the next file in a file list.

Parameters

[in] pfl Pointer to a file list returned by gfileOpenFileList()

Returns: A pointer to a file (or directory) name. Returns NULL if there are no more.

Note: The file name may contain the full directory path or may not depending on how the file system treats directories.; The returned buffer may be destroyed by the next call to any of gfileOpenFileList(), gfileReadFileList() or gfileCloseFileList(). Do not use this pointer after one of those calls.

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gfileRename()

gBool gfileRename	(	const char *	oldname,
		const char *	newname
	)

Rename file.

Parameters

[in]	oldname	The current file name
[in]	newname	The new name of the file

Returns: gTrue on success, gFalse otherwise

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gfileSetPos()

gBool gfileSetPos	(	GFILE *	f,
		gFileSize	pos
	)

Set the position of the read/write cursor.

Parameters

[in]	f	The file
[in]	pos	The position to which the cursor will be set

Returns: gTrue on success, gFalse otherwise

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gfileSync()

gBool gfileSync ( GFILE * f )

Syncs the file object (flushes the buffer)

Not supported by every file system

Parameters

[in] f The file

Returns: gTrue on success, gFalse otherwise

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gfileUnmount()

gBool gfileUnmount	(	char	fs,
		const char *	drive
	)

Unmount a logical drive (aka partition)

Does have no effect if gfileMount() as been called before hand

Parameters

[in]	fs	The file system (F for FatFS)
[in]	drive	The logical drive prefix

Returns: gTrue on success, gFalse otherwise

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gfileWrite()

gMemSize gfileWrite	(	GFILE *	f,
		const void *	buf,
		gMemSize	len
	)

Write to file.

Write a given amount of bytes to the file

The read/write cursor will not be reset when calling this function

Parameters

[in]	f	The file
[in]	buf	The buffer which contains the content that will be written to the file
[in]	len	Amount of bytes to write

Returns: Amount of bytes written

Function Class: Normal API, this function can be invoked by regular system threads.

Macro Definition Documentation

◆ GFILE_ALLOW_DEVICESPECIFIC

#define GFILE_ALLOW_DEVICESPECIFIC GFXOFF

Can the device be specified as part of the file name.

Note: If this is on then a device letter and a vertical bar can be prefixed on a file name to specify that it must be on a specific device.

Definition at line 209 of file gfile_options.h.

◆ GFILE_ALLOW_FLOATS

#define GFILE_ALLOW_FLOATS GFXOFF

Add floating point support to printg/scang etc.

Definition at line 200 of file gfile_options.h.

◆ GFILE_FATFS_EXTERNAL_LIB

#define GFILE_FATFS_EXTERNAL_LIB GFXOFF

TUse an external FATFS library instead of the uGFX inbuilt one.

Note: This is applicable when GFILE_NEED_FATFS is specified. It allows the programmer to use their own FATFS implementation provided the api matches the fatfs-0.10b API.; The users ffconf.h file still needs to be reachable when compiling uGFX.; If ffconf.h contains _FS_REENTRANT as true then the user provided simpleton routines must be compatible with uGFX threading.; If ffconf.h contains _USE_LFN == 3 then the user provided simpleton routines must be compatible with uGFX memory management.

Definition at line 231 of file gfile_options.h.

◆ GFILE_MAX_GFILES

#define GFILE_MAX_GFILES 3

The maximum number of open files.

Note: This count excludes gfileStdIn, gfileStdOut and gfileStdErr (if open by default).

Definition at line 217 of file gfile_options.h.

◆ GFILE_NEED_CHIBIOSFS

#define GFILE_NEED_CHIBIOSFS GFXOFF

Include ChibiOS BaseFileStream support.

Defaults to GFXOFF

Precondition: This is only relevant on the ChibiOS operating system.

Note: Use the gfileOpenBaseFileStream() call to open a GFILE based on a BaseFileStream. The BaseFileStream must already be open.; A GFile of this type cannot be opened by filename. The BaseFileStream must be pre-opened using the operating system.

Definition at line 170 of file gfile_options.h.

◆ GFILE_NEED_FATFS

#define GFILE_NEED_FATFS GFXOFF

Include the FAT file system driver based on the FATFS library.

Defaults to GFXOFF

Note: If GFILE_ALLOW_DEVICESPECIFIC is on then you can ensure that you are opening a file on the FAT file system by prefixing its name with "F|" (the letter 'F', followed by a vertical bar).; FATFS and PETITFS offer the same FAT file system support. They just use different constraints. PETITFS is smaller but has less features. Only one can be used at a time. The block interfaces are also different.

Definition at line 129 of file gfile_options.h.

◆ GFILE_NEED_FILELISTS

#define GFILE_NEED_FILELISTS GFXOFF

Include support for file list functions.

Defaults to GFXOFF

Note: Adds support for gfileOpenFileList(), gfileReadFileList() and gfileCloseFileList().

Definition at line 188 of file gfile_options.h.

◆ GFILE_NEED_MEMFS

#define GFILE_NEED_MEMFS GFXOFF

Include raw memory pointer support.

Defaults to GFXOFF

Note: Use the gfileOpenMemory() call to open a GFILE based on a memory pointer. The GFILE opened appears to be of unlimited size.; A GFile of this type cannot be opened by filename.

Definition at line 180 of file gfile_options.h.

◆ GFILE_NEED_NATIVEFS

#define GFILE_NEED_NATIVEFS GFXOFF

Include the operating system's native file system.

Defaults to GFXOFF

Note: If GFILE_ALLOW_DEVICESPECIFIC is on then you can ensure that you are opening a file on the native file system by prefixing its name with "N|" (the letter 'N', followed by a vertical bar).; If defined then the gfileStdOut and gfileStdErr handles use the operating system equivalent stdio and stderr. If it is not defined the gfileStdOut and gfileStdErr io is discarded.

Definition at line 158 of file gfile_options.h.

◆ GFILE_NEED_NOAUTOMOUNT

#define GFILE_NEED_NOAUTOMOUNT GFXOFF

Should the filesystem not be mounted automatically.

The filesystem is normally mounted automatically if the user does not do it manually. This option turns that off so the user must manually mount the file-system first.

Defaults to GFXOFF

Definition at line 31 of file gfile_options.h.

◆ GFILE_NEED_NOAUTOSYNC

#define GFILE_NEED_NOAUTOSYNC GFXOFF

Should the filesystem be synced automatically.

The filesystem will automatically be synced after an open() or write() call unless this feature is disabled.

If this feature is disabled, the user should sync the filesystem himself using gfileSync()

Not all filesystems implement the syncing feature. This feature will have no effect in such a case.

Defaults to GFXOFF

Definition at line 44 of file gfile_options.h.

◆ GFILE_NEED_PETITFS

#define GFILE_NEED_PETITFS GFXOFF

Include the FAT file system driver based on the PETITFS library.

Defaults to GFXOFF

Note: If GFILE_ALLOW_DEVICESPECIFIC is on then you can ensure that you are opening a file on the FAT file system by prefixing its name with "F|" (the letter 'F', followed by a vertical bar).; FATFS and PETITFS offer the same FAT file system support. They just use different constraints. PETITFS is smaller but has less features. Only one can be used at a time. The block interfaces are also different.; Due to the restrictions on the PETITFS library on writing, we do not implement writing.; PETITFS can only have one file open at a time.

Definition at line 145 of file gfile_options.h.

◆ GFILE_NEED_PRINTG

#define GFILE_NEED_PRINTG GFXOFF

Include printg, fprintg etc functions.

Defaults to GFXOFF

Precondition: To get the string sprintg functions you also need to define GFILE_NEED_STRINGS

Definition at line 52 of file gfile_options.h.

◆ GFILE_NEED_RAMFS

#define GFILE_NEED_RAMFS GFXOFF

Include the RAM file system.

Defaults to GFXOFF

Note: If GFILE_ALLOW_DEVICESPECIFIC is on then you can ensure that you are opening a file on the RAM file system by prefixing its name with "R|" (the letter 'R', followed by a vertical bar).; You must also define GFILE_RAMFS_SIZE with the size of the file system to be allocated in RAM.

Definition at line 116 of file gfile_options.h.

◆ GFILE_NEED_ROMFS

#define GFILE_NEED_ROMFS GFXOFF

Include the ROM file system.

Defaults to GFXOFF

Note: If GFILE_ALLOW_DEVICESPECIFIC is on then you can ensure that you are opening a file on the ROM file system by prefixing its name with "S|" (the letter 'S', followed by a vertical bar).; This requires a file called romfs_files.h to be in the users project include path. This file should include all the files converted to .h files using the file2c utility (using flags "-dbcs").

Definition at line 104 of file gfile_options.h.

◆ GFILE_NEED_SCANG

#define GFILE_NEED_SCANG GFXOFF

Include scang, fscang etc functions.

Defaults to GFXOFF

Precondition: To get the string sscang functions you also need to define GFILE_NEED_STRINGS

Definition at line 60 of file gfile_options.h.

◆ GFILE_NEED_STDIO

#define GFILE_NEED_STDIO GFXOFF

Map many stdio functions to their GFILE equivalent.

Defaults to GFXOFF

Note

This replaces the functions in stdio.h with equivalents

Do not include stdio.h as it has different conflicting definitions.

Definition at line 76 of file gfile_options.h.

◆ GFILE_NEED_STRINGS

#define GFILE_NEED_STRINGS GFXOFF

Include the string based file functions.

Defaults to GFXOFF

Definition at line 67 of file gfile_options.h.

◆ GFILE_NEED_USERFS

#define GFILE_NEED_USERFS GFXOFF

Include the USER file system.

Defaults to GFXOFF

Note: The User FS vmt strcture 'FsUSERVMT' must be defined and implemented in the user's project.; If GFILE_ALLOW_DEVICESPECIFIC is on then you can ensure that you are opening a file on the USER file system by prefixing its name with "U|" (the letter 'U', followed by a vertical bar). The letter 'U' as described above should be replaced by the actual device specifier letter in the user's FsUSERVMT structure. It is suggested that it is actually the letter 'U' that is used and it is important that the letter used is not one used by the other file systems.

Definition at line 91 of file gfile_options.h.

◆ GFILE_PETITFS_EXTERNAL_LIB

#define GFILE_PETITFS_EXTERNAL_LIB GFXOFF

TUse an external PETITFS library instead of the uGFX inbuilt one.

Note: This is applicable when GFILE_NEED_PETITFS is specified. It allows the programmer to use their own FATFS implementation provided the api matches the petitfs-0.03 API.; The users pffconf.h file still needs to be reachable when compiling uGFX.

Definition at line 241 of file gfile_options.h.

Typedef Documentation

◆ GFILE

typedef struct GFILE GFILE

A file pointer.

Definition at line 1 of file gfile.h.

Detailed Description

Functions

GFILE Functionality to be included

GFILE Optional Parameters

Typedefs

Function Documentation

◆ gfileClose()

◆ gfileCloseFileList()

◆ gfileDelete()

◆ gfileEOF()

◆ gfileExists()

◆ gfileGetFilesize()

◆ gfileGetPos()

◆ gfileGetSize()

◆ gfileMount()

◆ gfileOpen()

◆ gfileOpenChibiOSFileStream()

◆ gfileOpenFileList()

◆ gfileOpenMemory()

◆ gfileOpenString()

◆ gfileRead()

◆ gfileReadFileList()

◆ gfileRename()

◆ gfileSetPos()

◆ gfileSync()

◆ gfileUnmount()

◆ gfileWrite()

Macro Definition Documentation

◆ GFILE_ALLOW_DEVICESPECIFIC

◆ GFILE_ALLOW_FLOATS

◆ GFILE_FATFS_EXTERNAL_LIB

◆ GFILE_MAX_GFILES

◆ GFILE_NEED_CHIBIOSFS

◆ GFILE_NEED_FATFS

◆ GFILE_NEED_FILELISTS

◆ GFILE_NEED_MEMFS

◆ GFILE_NEED_NATIVEFS

◆ GFILE_NEED_NOAUTOMOUNT

◆ GFILE_NEED_NOAUTOSYNC

◆ GFILE_NEED_PETITFS

◆ GFILE_NEED_PRINTG

◆ GFILE_NEED_RAMFS

◆ GFILE_NEED_ROMFS

◆ GFILE_NEED_SCANG

◆ GFILE_NEED_STDIO

◆ GFILE_NEED_STRINGS

◆ GFILE_NEED_USERFS

◆ GFILE_PETITFS_EXTERNAL_LIB

Typedef Documentation

◆ GFILE