File System

Typedefs
typedef struct fsFile_t	fsFile_t
	Opaque type of a file.

Enumerations
enum	fsOpenFlags_t {   FS_OPEN_READ = 1, FS_OPEN_WRITE = 2, FS_OPEN_CREATE = 4, FS_OPEN_RESET = 8,   FS_OPEN_APPEND = 16 }
	Flags for fsOpen(). More...
enum	fsSeekWhence_t { FS_WHENCE_SET, FS_WHENCE_END, FS_WHENCE_CUR }
	Posible seek positions, see fsSeek(). More...

Functions
int	fsSetFileNamePrefix (const char *prefix)
	Set the common file name prefix. More...
int	fsPushFileNamePrefix (const char *prefix)
	Push a new item on the file name prefix stack. More...
int	fsPopFileNamePrefix (void)
	Remove the top item on the file name prefix stack. More...
const char *	fsGetFileNamePrefix (void)
	Return the current prefix being used. More...
int	fsOpen (const char *name, int flags, fsFile_t **file)
	Open the selected file to input and/or output. More...
int	fsClose (fsFile_t *f)
	Close a file handle. More...
int	fsRead (fsFile_t *f, int n, void *p)
	Try to read a number of bytes from a file. More...
int	fsReadByte (fsFile_t *f)
	Try to read the next byte from the file. More...
int	fsReadUntil (fsFile_t *f, const uint8_t *delims, int ndelim, int n, void *p)
	Read bytes from the input file until either one of delims bytes is found, or n bytes have been read. More...
int	fsWrite (fsFile_t *f, int n, const void *p)
	Try to write a number of bytes to a file. More...
int	fsWriteByte (fsFile_t *f, int b)
	Try to write a byte to a file. More...
int	fsTell (fsFile_t *f)
	Return the current read/write position of a file. More...
int	fsSeek (fsFile_t *f, int whence, int offset)
	Set the read/write position for a file. More...
int	fsLength (fsFile_t *f)
	Return the length of an open file in bytes. More...
int	fsRemove (const char *name)
	Delete file name from the file system. More...
int	fsRename (const char *oldname, const char *newname)
	Rename the file oname to newname. More...
int	fsExist (const char *name)
	Check if file name exists. More...

Detailed Description

Rationale

File system API differs heavily between platforms. But more than 90% of all uses require the same simple basic functions. By defining them in a portable manner we can handle most porting issues without needing complicated implementations on simpler platforms.

Introduction

This module defines a basic abstraction over the common operations of all file systems. Functionality is added only if easily implementable on all supported file systems, so it may not be enough/adequate for certain operations, specially in case of access to some platform-dependent meta-data.

The sort of operations covered here are:

• Opening files;
• Basic I/O (block/string oriented I/O);

Note that some directory-related operations are not included (change current directory, create/remove directory). In place of this, it is used the concept of file name prefix (see fsSetFileNamePrefix()). Each operation on files names will prepend this prefix to the file name before operating. This allows for quick adaptation between architectures that have different concepts for directory/volume/working-unit.

The file name prefixes are also stored as a stack, allowing entries to be "pushed" and "poped" (see fsPushFileNamePrefix() and fsPopFileNamePrefix()), this way a code that temporarily needs to set the file prefix do not need to store the current one on a temporary variable to restore later.

Telium

On Telium architecture, use the file name prefix to define which volume to use, but note that:

• The prefix string should include the full volume name, terminating with '/': "/VOLUME/";
• The volume is not automatically created, this must be done outside this library

Unicapt

Global files are currently not supported on Unicapt32.

Todo:

Directory iteration

Enumeration Type Documentation

enum fsOpenFlags_t

Flags for fsOpen().

The FS_OPEN_READ and FS_OPEN_WRITE options are not strict, i.e., a file open for reading may have write allowed and a file open for writing may have read allowed. The strictest permission possible for a given architecture will be used.

Enumerator
FS_OPEN_READ	Open file for reading.
FS_OPEN_WRITE	Open file for writing.
FS_OPEN_CREATE	Create file if not found.
FS_OPEN_RESET	Reset file if present.
FS_OPEN_APPEND	Move position to FS_WHENCE_END after open, forces FS_OPEN_WRITE.

enum fsSeekWhence_t

Posible seek positions, see fsSeek().

Enumerator
FS_WHENCE_SET	Seek from the start of file.
FS_WHENCE_END	Seek from the end of file.
FS_WHENCE_CUR	Seek from the current position.

Function Documentation

int fsClose

(

fsFile_t *

f

)

Close a file handle.

Parameters

f	Handle to open file.

Returns

BASE_ERR_OK on success.

BASE_ERR_INVALID_HANDLE if f is invalid or NULL.

See also

fsOpen

int fsExist

(

const char *

name

)

Check if file name exists.

Parameters

name	Name of file to check.

Returns

Non-zero if file exists

Zero otherwise

Attention

The fact that the file exists does not imply that it can be opened by the caller application!

const char* fsGetFileNamePrefix

(

void

)

Return the current prefix being used.

Returns

Pointer to the prefix in use. The returned string must not be changed, use fsSetFileNamePrefix() to do this instead.

See also

fsSetFileNamePrefix

int fsLength

(

fsFile_t *

f

)

Return the length of an open file in bytes.

The current file pointer is not changed.

This is equivalent to:

int fileSize(fsFile_t *f) {
  // FIXME: no error handling!
  int orig = fsTell(f);
  int siz = fsSeek(f, FS_WHENCE_END, 0);
  fsSeek(f, FS_WHENCE_SET, orig);
  return siz;
}

Parameters

f	Handle to open file.

Returns

Non-negative size of file f.

BASE_ERR_INVALID_HANDLE if f is invalid.

BASE_ERR_ACCESS if this operation is not allowed on this type of file.

int fsOpen	(	const char *	name,
		int	flags,
		fsFile_t **	file
	)

Open the selected file to input and/or output.

Note the double indirection on the file parameter, to use this function:

fsFile_t *file;
int error = fsOpen(name, FS_OPEN_READ | FS_OPEN_WRITE | FS_OPEN_CREATE, &file);
// use file...
fsClose(file);

Parameters

	name	File name. The actual name sent to the OS has the value defined by fsSetFileNamePrefix() prepended.
	flags	File opening flags OR'ed together, see fsOpenFlags_t. At least one of FS_OPEN_READ or FS_OPEN_WRITE must be set.
[out]	file	On successful return, a handle to the open file.

Returns

BASE_ERR_OK on success.

BASE_ERR_DATA_NOT_FOUND if file was not found.

BASE_ERR_RESOURCE_PB if could not allocate a new handle.

BASE_ERR_ACCESS do not have permission to access file.

BASE_ERR_OVERFLOW if name (or the concatenation of name and prefix) is too large.

BASE_ERR_INVALID_PARAMETER if name, flags or file are invalid.

See also

fsClose

int fsPopFileNamePrefix

(

void

)

Remove the top item on the file name prefix stack.

If the file name prefix stack has at least two elements, this call will remove the "top" element of the stack. If the list has a single element, this call has no effect (and the current value is kept).

Returns

BASE_ERR_OK

int fsPushFileNamePrefix

(

const char *

prefix

)

Push a new item on the file name prefix stack.

This call will change the value that fsGetFileNamePrefix() returns but keep the previous values untouched. A call to fsPopFileNamePrefix() may be used to restore previous values.

Parameters

prefix

File name prefix to use.

Returns

BASE_ERR_OK on success

BASE_ERR_INVALID_PARAMETER if prefix is not valid on current architecture.

BASE_ERR_OVERFLOW if prefix is too large, or if file name prefix stack is too long

int fsRead	(	fsFile_t *	f,
		int	n,
		void *	p
	)

Try to read a number of bytes from a file.

Reads up to n bytes from the file, depending on availability. Never reads more than n bytes.

Parameters

	f	Handle to open file.
	n	Number of bytes to read.
[out]	p	Where to store the bytes read. Must have place for upto n bytes.

Returns

Number of bytes actually read (zero if no more bytes to read – end of file).

BASE_ERR_INVALID_HANDLE if f is invalid.

BASE_ERR_ACCESS if do not have permission to read from f.

BASE_ERR_INVALID_PARAMETER if p is NULL.

See also

fsReadByte fsReadUntil

int fsReadByte

(

fsFile_t *

f

)

Try to read the next byte from the file.

Parameters

f	Handle to open file.

Returns

Non-negative value of byte read, a return less than zero signals error.

BASE_ERR_INVALID_HANDLE if f is invalid.

BASE_ERR_ACCESS if do not have permission to read from f.

BASE_ERR_DATA_NOT_FOUND if reached end of file.

See also

fsRead fsReadUntil

int fsReadUntil	(	fsFile_t *	f,
		const uint8_t *	delims,
		int	ndelim,
		int	n,
		void *	p
	)

Read bytes from the input file until either one of delims bytes is found, or n bytes have been read.

The delimiter character is included on the output buffer.

Note that p is not zero-terminated, the caller must use the return from this function to determine the number of bytes written to p and place the terminating zero if necessary.

Example:

char buf[N];
int nread;
nread = fsReadUntil(f, "\n", -1, N - 1, buf);
if (nread >= 0) buf[nread] = '\0'; // force zero-termination

Parameters

	f	Handle to open file.
	delims	Bytes to use as delimiters.
	ndelim	Number of bytes in delims. May be negative to use strlen(delims).
	n	Read upto n bytes from input.
[out]	p	Where to store the data read, must have space for upto n bytes.

Returns

Non-negative number of bytes read (zero if end of file).

BASE_ERR_INVALID_HANDLE if f is invalid.

BASE_ERR_ACCESS if do not have permission to read from f.

BASE_ERR_INVALID_PARAMETER if delims or p are NULL.

See also

fsRead fsReadByte

int fsRemove

(

const char *

name

)

Delete file name from the file system.

The behavior is undefined if the file is currently open.

Parameters

name	Name of file to delete.

Returns

BASE_ERR_OK if file was deleted.

BASE_ERR_DATA_NOT_FOUND if name does not exist.

BASE_ERR_ACCESS if could not access file (in use?)

BASE_ERR_RESOURCE_PB on file system access error

int fsRename	(	const char *	oldname,
		const char *	newname
	)

Rename the file oname to newname.

Both oldname and newname should not be open. The behavior is undefined if oldname and newname refer to diferent directories or volumes (most implementations will fail).

Parameters

oldname	Original (current) name of file.
newname	New name of file.

Returns

BASE_ERR_OK if file was deleted.

BASE_ERR_DATA_NOT_FOUND if oldname does not exist.

BASE_ERR_ACCESS if could not access file (in use?)

BASE_ERR_RESOURCE_PB on file system access error

int fsSeek	(	fsFile_t *	f,
		int	whence,
		int	offset
	)

Set the read/write position for a file.

Trying to move before the start of the file or after one past the end of the file has undefined behavior, it may fail or move the position to one of the edges of the file, depending on the platform. Do not depend on either behavior.

Parameters

f	Handle to open file.
whence	Where to seek from, see fsSeekWhence_t.
offset	Distance to seek, positive to seek forward, negative to seek backward.

Returns

Non-negative new position inside the file.

BASE_ERR_INVALID_HANDLE if f is invalid.

BASE_ERR_ACCESS if this operation is not allowed on this type of file.

BASE_ERR_INVALID_PARAMETER if whence is not FS_WHENCE_SET, FS_WHENCE_END or FS_WHENCE_CUR.

See also

fsTell

int fsSetFileNamePrefix

(

const char *

prefix

)

Set the common file name prefix.

Each operation on files by name prepend this prefix (without any processing!) before calling the OS.

Parameters

prefix

File name prefix to use.

Returns

BASE_ERR_OK on success.

BASE_ERR_INVALID_PARAMETER if prefix is not valid on current architecture.

BASE_ERR_OVERFLOW if prefix is too large.

See also

fsGetFileNamePrefix fsOpen

int fsTell

(

fsFile_t *

f

)

Return the current read/write position of a file.

Parameters

f	Handle to open file.

Returns

Non-negative file position on success.

BASE_ERR_INVALID_HANDLE if f is invalid.

BASE_ERR_ACCESS if this operation is not allowed on this type of file.

See also

fsSeek

int fsWrite	(	fsFile_t *	f,
		int	n,
		const void *	p
	)

Try to write a number of bytes to a file.

Writes upto to n bytes to the file. Depending on available space may not be able to write all the requested bytes. Writing on the end of the file to append is allowed.

Parameters

f	Handle to open file.
n	Number of bytes to write.
p	Buffer with data to write.

Returns

Number of bytes written on success.

BASE_ERR_INVALID_HANDLE if f is invalid.

BASE_ERR_ACCESS if do not have permission to write to f.

See also

fsWriteByte

int fsWriteByte	(	fsFile_t *	f,
		int	b
	)

Try to write a byte to a file.

Parameters

f	Handle to open file.
b	Byte value to write. Only the least significant 8-bits are used, truncating b to the range [0, 255].

Returns

BASE_ERR_OK if byte was written.

BASE_ERR_INVALID_HANDLE if f is invalid.

BASE_ERR_ACCESS if do not have permission to write to f.

BASE_ERR_RESOURCE_PB if could not write byte.

See also

fsWrite