version 2.8
GFILE

Detailed Description

Module which contains operating system independent file I/O.

Functions

bool_t gfileExists (const char *fname)
 Check if file exists. More...
 
bool_t gfileDelete (const char *fname)
 Delete file. More...
 
long int gfileGetFilesize (const char *fname)
 Get the size of a file. More...
 
bool_t gfileRename (const char *oldname, const char *newname)
 Rename file. More...
 
GFILEgfileOpen (const char *fname, const char *mode)
 Open file. More...
 
void gfileClose (GFILE *f)
 Close file. More...
 
size_t gfileRead (GFILE *f, void *buf, size_t len)
 Read from file. More...
 
size_t gfileWrite (GFILE *f, const void *buf, size_t len)
 Write to file. More...
 
long int gfileGetPos (GFILE *f)
 Get the current position of the read/write cursor. More...
 
bool_t gfileSetPos (GFILE *f, long int pos)
 Set the position of the read/write cursor. More...
 
long int gfileGetSize (GFILE *f)
 Get the size of file. More...
 
bool_t gfileEOF (GFILE *f)
 Check for EOF. More...
 
bool_t gfileMount (char fs, const char *drive)
 Mount a logical drive (aka partition) More...
 
bool_t gfileUnmount (char fs, const char *drive)
 Unmount a logical drive (aka partition) More...
 
bool_t gfileSync (GFILE *f)
 Syncs the file object (flushes the buffer) More...
 
gfileList * gfileOpenFileList (char fs, const char *path, bool_t 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...
 
GFILEgfileOpenChibiOSFileStream (void *FileStreamPtr, const char *mode)
 Open file from a ChibiOS FileStream. More...
 
GFILEgfileOpenMemory (void *memptr, const char *mode)
 Open file from a memory pointer. More...
 
GFILEgfileOpenString (char *str, const char *mode)
 Open file from a null terminated C string. More...
 

GFILE Functionality to be included

#define GFILE_NEED_NOAUTOMOUNT   FALSE
 Should the filesystem not be mounted automatically. More...
 
#define GFILE_NEED_NOAUTOSYNC   FALSE
 Should the filesystem be synced automatically. More...
 
#define GFILE_NEED_PRINTG   FALSE
 Include printg, fprintg etc functions. More...
 
#define GFILE_NEED_SCANG   FALSE
 Include scang, fscang etc functions. More...
 
#define GFILE_NEED_STRINGS   FALSE
 Include the string based file functions. More...
 
#define GFILE_NEED_STDIO   FALSE
 Map many stdio functions to their GFILE equivalent. More...
 
#define GFILE_NEED_USERFS   FALSE
 Include the USER file system. More...
 
#define GFILE_NEED_ROMFS   FALSE
 Include the ROM file system. More...
 
#define GFILE_NEED_RAMFS   FALSE
 Include the RAM file system. More...
 
#define GFILE_NEED_FATFS   FALSE
 Include the FAT file system driver based on the FATFS library. More...
 
#define GFILE_NEED_PETITFS   FALSE
 Include the FAT file system driver based on the PETITFS library. More...
 
#define GFILE_NEED_NATIVEFS   FALSE
 Include the operating system's native file system. More...
 
#define GFILE_NEED_CHIBIOSFS   FALSE
 Include ChibiOS BaseFileStream support. More...
 
#define GFILE_NEED_MEMFS   FALSE
 Include raw memory pointer support. More...
 
#define GFILE_NEED_FILELISTS   FALSE
 Include support for file list functions. More...
 

GFILE Optional Parameters

#define GFILE_ALLOW_FLOATS   FALSE
 Add floating point support to printg/scang etc. More...
 
#define GFILE_ALLOW_DEVICESPECIFIC   FALSE
 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   FALSE
 TUse an external FATFS library instead of the uGFX inbuilt one. More...
 
#define GFILE_PETITFS_EXTERNAL_LIB   FALSE
 TUse an external PETITFS library instead of the uGFX inbuilt one. More...
 

Typedefs

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

Function Documentation

void gfileClose ( GFILE f)

Close file.

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

Parameters
[in]fThe file
Function Class:
Normal API, this function can be invoked by regular system threads.
void gfileCloseFileList ( gfileList *  pfl)

Close a file list.

Parameters
[in]pflPointer to a file list returned by gfileOpenFileList()
Function Class:
Normal API, this function can be invoked by regular system threads.
bool_t gfileDelete ( const char *  fname)

Delete file.

Parameters
[in]fnameThe file name
Returns
TRUE on success, FALSE otherwise
Function Class:
Normal API, this function can be invoked by regular system threads.
bool_t gfileEOF ( GFILE f)

Check for EOF.

Checks if the cursor is at the end of the file

Parameters
[in]fThe file
Returns
TRUE if EOF, FALSE otherwise
Function Class:
Normal API, this function can be invoked by regular system threads.
bool_t gfileExists ( const char *  fname)

Check if file exists.

Parameters
[in]fnameThe file name
Returns
TRUE if file exists, FALSE otherwise
Function Class:
Normal API, this function can be invoked by regular system threads.
long int gfileGetFilesize ( const char *  fname)

Get the size of a file.

Note
Please use gfileGetSize() if the file is opened
Parameters
[in]fnameThe file name
Returns
File size on success, -1 on error
Function Class:
Normal API, this function can be invoked by regular system threads.
long int gfileGetPos ( GFILE f)

Get the current position of the read/write cursor.

Parameters
[in]fThe file
Returns
The current position in the file
Function Class:
Normal API, this function can be invoked by regular system threads.
long int gfileGetSize ( GFILE f)

Get the size of file.

Note
Please use gfileGetFilesize() if the file is not opened
Parameters
[in]fThe file
Returns
The size of the file
Function Class:
Normal API, this function can be invoked by regular system threads.
bool_t 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]fsThe file system (F for FatFS)
[in]driveThe logical drive prefix
Returns
TRUE on success, FALSE otherwise
Function Class:
Normal API, this function can be invoked by regular system threads.
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]fnameThe file name
[in]modeThe 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.
GFILE* gfileOpenChibiOSFileStream ( void *  FileStreamPtr,
const char *  mode 
)

Open file from a ChibiOS FileStream.

Parameters
[in]FileStreamPtrThe BaseFileStream (ChibiOS V2) or FileStream (ChibiOS V3) to open as a GFILE
[in]modeThe 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.
gfileList* gfileOpenFileList ( char  fs,
const char *  path,
bool_t  dirs 
)

Open a file list.

Parameters
[in]fsThe file system (F for FatFS)
[in]pathPath information to pass to the file system
[in]dirsPass TRUE to get directories only, FALSE 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 TRUE 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.
GFILE* gfileOpenMemory ( void *  memptr,
const char *  mode 
)

Open file from a memory pointer.

Parameters
[in]memptrThe pointer to the memory
[in]modeThe 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.
GFILE* gfileOpenString ( char *  str,
const char *  mode 
)

Open file from a null terminated C string.

Parameters
[in]strThe pointer to the string or string buffer
[in]modeThe 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.
size_t gfileRead ( GFILE f,
void *  buf,
size_t  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]fThe file
[out]bufThe buffer in which to save the content that has been read from the file
[in]lenAmount of bytes to read
Returns
Amount of bytes read
Function Class:
Normal API, this function can be invoked by regular system threads.
const char* gfileReadFileList ( gfileList *  pfl)

Get the next file in a file list.

Parameters
[in]pflPointer 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.
bool_t gfileRename ( const char *  oldname,
const char *  newname 
)

Rename file.

Parameters
[in]oldnameThe current file name
[in]newnameThe new name of the file
Returns
TRUE on success, FALSE otherwise
Function Class:
Normal API, this function can be invoked by regular system threads.
bool_t gfileSetPos ( GFILE f,
long int  pos 
)

Set the position of the read/write cursor.

Parameters
[in]fThe file
[in]posThe position to which the cursor will be set
Returns
TRUE on success, FALSE otherwise
Function Class:
Normal API, this function can be invoked by regular system threads.
bool_t gfileSync ( GFILE f)

Syncs the file object (flushes the buffer)

Not supported by every file system

Parameters
[in]fThe file
Returns
TRUE on success, FALSE otherwise
Function Class:
Normal API, this function can be invoked by regular system threads.
bool_t 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]fsThe file system (F for FatFS)
[in]driveThe logical drive prefix
Returns
TRUE on success, FALSE otherwise
Function Class:
Normal API, this function can be invoked by regular system threads.
size_t gfileWrite ( GFILE f,
const void *  buf,
size_t  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]fThe file
[in]bufThe buffer which contains the content that will be written to the file
[in]lenAmount 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

#define GFILE_ALLOW_DEVICESPECIFIC   FALSE

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.

#define GFILE_ALLOW_FLOATS   FALSE

Add floating point support to printg/scang etc.

Definition at line 200 of file gfile_options.h.

#define GFILE_FATFS_EXTERNAL_LIB   FALSE

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.

#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.

#define GFILE_NEED_CHIBIOSFS   FALSE

Include ChibiOS BaseFileStream support.

Defaults to FALSE

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.

#define GFILE_NEED_FATFS   FALSE

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

Defaults to FALSE

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.

#define GFILE_NEED_FILELISTS   FALSE

Include support for file list functions.

Defaults to FALSE

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

Definition at line 188 of file gfile_options.h.

#define GFILE_NEED_MEMFS   FALSE

Include raw memory pointer support.

Defaults to FALSE

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.

#define GFILE_NEED_NATIVEFS   FALSE

Include the operating system's native file system.

Defaults to FALSE

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.

#define GFILE_NEED_NOAUTOMOUNT   FALSE

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 FALSE

Definition at line 31 of file gfile_options.h.

#define GFILE_NEED_NOAUTOSYNC   FALSE

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 FALSE

Definition at line 44 of file gfile_options.h.

#define GFILE_NEED_PETITFS   FALSE

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

Defaults to FALSE

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.

#define GFILE_NEED_PRINTG   FALSE

Include printg, fprintg etc functions.

Defaults to FALSE

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

Definition at line 52 of file gfile_options.h.

#define GFILE_NEED_RAMFS   FALSE

Include the RAM file system.

Defaults to FALSE

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.

#define GFILE_NEED_ROMFS   FALSE

Include the ROM file system.

Defaults to FALSE

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.

#define GFILE_NEED_SCANG   FALSE

Include scang, fscang etc functions.

Defaults to FALSE

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

Definition at line 60 of file gfile_options.h.

#define GFILE_NEED_STDIO   FALSE

Map many stdio functions to their GFILE equivalent.

Defaults to FALSE

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.

#define GFILE_NEED_STRINGS   FALSE

Include the string based file functions.

Defaults to FALSE

Definition at line 67 of file gfile_options.h.

#define GFILE_NEED_USERFS   FALSE

Include the USER file system.

Defaults to FALSE

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.

#define GFILE_PETITFS_EXTERNAL_LIB   FALSE

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

typedef struct GFILE GFILE

A file pointer.

Definition at line 34 of file gfile.h.