filesystem.h File Reference

Data Structures
struct	fs_directory_entry_t
	A VFS directory entry. Files AND directories have these, but internally there is also a tree of fs_tree_t* which is used for faster access and caching the structure to RAM. More...
struct	filesystem_t
	Defines a filesystem driver. More...
struct	storage_device_t
	Represents a block storage device e.g. a hard disk, DVD-ROM drive, etc. More...
struct	fs_tree_t
	Used internally by filesystem.c to cache directories to RAM. More...
struct	fs_handle_t
	The data for an open file descriptor. More...

Macros
#define	FD_MAX   1024
	Maximum number of file descriptors which can be open at the same time. More...
#define	IOBUFSZ   8192
	Default size of IO buffer in open file. More...
#define	_O_APPEND   0x00000001
#define	_O_CREAT   0x00000002
#define	_O_RDONLY   0x00000004
#define	_O_WRONLY   0x00000008
#define	_O_RDWR   (_O_WRONLY|_O_RDONLY)
#define	FS_DIRECTORY   0x00000001 /* Entry is a directory */
#define	FS_MOUNTPOINT   0x00000002 /* Entry is a mountpoint */

Typedefs
typedef uint16_t	mode_t
typedef void *(*	get_directory) (void *)
typedef int(*	mount_volume) (const char *, const char *)
typedef bool(*	read_file) (void *, uint64_t, uint32_t, unsigned char *)
typedef bool(*	write_file) (void *, uint64_t, uint32_t, unsigned char *)
typedef uint64_t(*	create_file) (void *, const char *, size_t)
typedef bool(*	truncate_file) (void *, size_t)
typedef uint64_t(*	create_dir) (void *, const char *)
typedef bool(*	delete_file) (void *, const char *)
typedef bool(*	delete_dir) (void *, const char *)
typedef int(*	block_read) (void *, uint64_t, uint32_t, unsigned char *)
typedef int(*	block_write) (void *, uint64_t, uint32_t, const unsigned char *)

Enumerations
enum	fs_handle_type_t { file_input , file_output , file_random }
	File handle access type. More...

Functions
int	register_filesystem (filesystem_t *newfs)
	Register a new filesystem. More...
filesystem_t *	find_filesystem (const char *name)
	Find a filesystem by name. More...
int	register_storage_device (storage_device_t *newdev)
	Register a new storage device. More...
storage_device_t *	find_storage_device (const char *name)
	Find a storage device by name. More...
int	read_storage_device (const char *name, uint64_t start_block, uint32_t bytes, unsigned char *data)
	Read blocks from storage device by name. More...
int	write_storage_device (const char *name, uint64_t start_block, uint32_t bytes, const unsigned char *data)
	Write blocks to storage device by name. More...
int	attach_filesystem (const char *virtual_path, filesystem_t *fs, void *opaque)
	Attach a filesystem to a VFS directory. Do not use this function for end user features, use filesystem_mount() instead. More...
int	filesystem_mount (const char *pathname, const char *device, const char *filesystem_driver)
	High level mount function. More...
void	init_filesystem ()
	Initialise the filesystem This loads the DummyFS filesystem which manages the root directory until any other driver is loaded. DummyFS is a dummy and does nothing. More...
fs_directory_entry_t *	fs_get_items (const char *pathname)
	Get a list of files in a directory. The directory path must be fully qualified from the root directory and must contain no trailing slash. More...
bool	fs_is_directory (const char *pathname)
	Returns true if the given path is a directory, false if it is a file. More...
fs_directory_entry_t *	fs_get_file_info (const char *pathandfile)
	Retrieve file information on any arbitrary filename. The item requested can be a file, or a directory. More...
fs_directory_entry_t *	fs_create_file (const char *pathandfile, size_t bytes)
	Create a new empty file. More...
fs_directory_entry_t *	fs_create_directory (const char *pathandfile)
	Create a new empty directory. More...
int	fs_truncate_file (fs_directory_entry_t *file, uint32_t length)
	Truncate an existing file to new length. More...
int	fs_read_file (fs_directory_entry_t *file, uint32_t start, uint32_t length, unsigned char *buffer)
	Read raw bytes from any arbitrary file. More...
int	_open (const char *filename, int oflag)
	POSIX style _open function. More...
int	_read (int fd, void *buffer, unsigned int count)
	POSIX _read function, reads bytes from an open file. More...
int	_write (int fd, void *buffer, unsigned int count)
	POSIX _write function, writes bytes to an open file. More...
int	_close (uint32_t fd)
	POSIX _close function, closes an open file. More...
int	_eof (int fd)
	POSIX _eof function. More...
int64_t	_lseek (int fd, uint64_t offset, uint64_t origin)
	Seek to given position in a file. More...
int64_t	_tell (int fd)
	Obtain current file position. More...
int	unlink (const char *pathname)
	Delete a file (not a directory) More...
int	mkdir (const char *pathname, mode_t mode)
	Make a directory. More...
int	rmdir (const char *pathname)
	Remove a directory. More...
int	ftruncate (int fd, uint32_t length)
	Truncate a file to the new length. More...
bool	fs_delete_file (const char *pathandfile)
	Low level delete file. More...
bool	fs_delete_directory (const char *pathandfile)
	Delete a directory. More...

Detailed Description

Author

Craig Edwards (craig.nosp@m.edwa.nosp@m.rds@b.nosp@m.rain.nosp@m.box.c.nosp@m.c)

Copyright

Copyright (c) 2012-2023

Macro Definition Documentation

_O_APPEND

#define _O_APPEND   0x00000001

_O_CREAT

#define _O_CREAT   0x00000002

_O_RDONLY

#define _O_RDONLY   0x00000004

_O_RDWR

#define _O_RDWR   (_O_WRONLY|_O_RDONLY)

_O_WRONLY

#define _O_WRONLY   0x00000008

FD_MAX

#define FD_MAX   1024

Maximum number of file descriptors which can be open at the same time.

FS_DIRECTORY

#define FS_DIRECTORY   0x00000001 /* Entry is a directory */

FS_MOUNTPOINT

#define FS_MOUNTPOINT   0x00000002 /* Entry is a mountpoint */

IOBUFSZ

#define IOBUFSZ   8192

Default size of IO buffer in open file.

Typedef Documentation

block_read

typedef int(* block_read) (void *, uint64_t, uint32_t, unsigned char *)

block_write

typedef int(* block_write) (void *, uint64_t, uint32_t, const unsigned char *)

create_dir

typedef uint64_t(* create_dir) (void *, const char *)

create_file

typedef uint64_t(* create_file) (void *, const char *, size_t)

delete_dir

typedef bool(* delete_dir) (void *, const char *)

delete_file

typedef bool(* delete_file) (void *, const char *)

get_directory

typedef void*(* get_directory) (void *)

mode_t

typedef uint16_t mode_t

mount_volume

typedef int(* mount_volume) (const char *, const char *)

read_file

typedef bool(* read_file) (void *, uint64_t, uint32_t, unsigned char *)

truncate_file

typedef bool(* truncate_file) (void *, size_t)

write_file

typedef bool(* write_file) (void *, uint64_t, uint32_t, unsigned char *)

Enumeration Type Documentation

fs_handle_type_t

enum fs_handle_type_t

File handle access type.

Enumerator
file_input	Open for input.
file_output	Open for output.
file_random	Open for input and output.

Function Documentation

_close()

int _close

(

uint32_t

fd

)

POSIX _close function, closes an open file.

Parameters

fd	file descriptor

Returns

int zero on success, -1 on error

_eof()

int _eof

(

int

fd

)

POSIX _eof function.

reports if we have reached the end of file marker on any open file.

Parameters

fd	file descriptor

Returns

int zero if not EOF, 1 if EOF, -1 on error

_lseek()

int64_t _lseek	(	int	fd,
		uint64_t	offset,
		uint64_t	origin
	)

Seek to given position in a file.

Note

offset + origin should be <= current file size

Parameters

fd	file descriptor
offset	offset from origin point
origin	origin point in file

Returns

int64_t new file position

_open()

int _open	(	const char *	filename,
		int	oflag
	)

POSIX style _open function.

opens a file for read or write access, or creates a new file.

Parameters

filename	Filename to create (fully qualified name)
oflag	open state for the file

Returns

int zero on success, -1 on error

_read()

int _read	(	int	fd,
		void *	buffer,
		unsigned int	count
	)

POSIX _read function, reads bytes from an open file.

Parameters

fd	file descriptor
buffer	buffer to receive data
count	count of bytes to read

Returns

int zero on success, -1 on error

_tell()

int64_t _tell

(

int

fd

)

Obtain current file position.

Parameters

fd	file descriptor

Returns

int64_t position in file

_write()

int _write	(	int	fd,
		void *	buffer,
		unsigned int	count
	)

POSIX _write function, writes bytes to an open file.

Parameters

fd	file descriptor
buffer	buffer containing data to write
count	count of bytes to write

Returns

int zero on success, -1 on error

attach_filesystem()

int attach_filesystem	(	const char *	virtual_path,
		filesystem_t *	fs,
		void *	opaque
	)

Attach a filesystem to a VFS directory. Do not use this function for end user features, use filesystem_mount() instead.

Note

The opaque data is optional and if included is driver-specific.

Parameters

virtual_path	virtual pathname in the VFS
fs	Filesystem driver name
opaque	Opaque data used by the filesystem driver

Returns

int nonzero on success

filesystem_mount()

int filesystem_mount	(	const char *	pathname,
		const char *	device,
		const char *	filesystem_driver
	)

High level mount function.

Parameters

pathname	VFS path to mount device/driver to
device	block device name
filesystem_driver	filesystem driver name

Returns

int 1 for success, 0 for failure

find_filesystem()

filesystem_t* find_filesystem

(

const char *

name

)

Find a filesystem by name.

Parameters

name	Name of filesystem to find

Returns

filesystem_t* Pointer to filesystem if found, or NULL

find_storage_device()

storage_device_t* find_storage_device

(

const char *

name

)

Find a storage device by name.

Parameters

name	Name of storage device to find

Returns

storage_device_t* Pointer to storage device if found, or NULL

fs_create_directory()

fs_directory_entry_t* fs_create_directory

(

const char *

pathandfile

)

Create a new empty directory.

Parameters

pathandfile	fully qualified path to new directory to create
bytes	size in bytes of directory to create

Returns

fs_directory_entry_t* information on new directory on success or NULL

fs_create_file()

fs_directory_entry_t* fs_create_file	(	const char *	pathandfile,
		size_t	bytes
	)

Create a new empty file.

Parameters

pathandfile	fully qualified path to new file to create
bytes	size in bytes of file to create

Returns

fs_directory_entry_t* information on new file on success or NULL

fs_delete_directory()

bool fs_delete_directory

(

const char *

pathandfile

)

Delete a directory.

Parameters

pathandfile

fully qualified path to file

Returns

true if directory was deleted

fs_delete_file()

bool fs_delete_file

(

const char *

pathandfile

)

Low level delete file.

Parameters

pathandfile

path and filename

Returns

true if file was deleted

fs_get_file_info()

fs_directory_entry_t* fs_get_file_info

(

const char *

pathandfile

)

Retrieve file information on any arbitrary filename. The item requested can be a file, or a directory.

Parameters

pathandfile

Path to file or directory

Returns

fs_directory_entry_t* information on the file.

fs_get_items()

fs_directory_entry_t* fs_get_items

(

const char *

pathname

)

Get a list of files in a directory. The directory path must be fully qualified from the root directory and must contain no trailing slash.

Parameters

pathname

fully qualified directory name

Returns

fs_directory_entry_t* linked list of items, or NULL if empty directory

fs_is_directory()

bool fs_is_directory

(

const char *

pathname

)

Returns true if the given path is a directory, false if it is a file.

Parameters

pathname

full qualified vfs path

Returns

true is a directory

false is a file

fs_read_file()

int fs_read_file	(	fs_directory_entry_t *	file,
		uint32_t	start,
		uint32_t	length,
		unsigned char *	buffer
	)

Read raw bytes from any arbitrary file.

Parameters

file	File to read from
start	starting byte position
length	length of data to read, starting at the starting position
buffer	Buffer to receive read data

Returns

int nonzero on error

fs_truncate_file()

int fs_truncate_file	(	fs_directory_entry_t *	file,
		uint32_t	length
	)

Truncate an existing file to new length.

Note

Any data beyond the new length is discarded and may not be recoverable.

Parameters

file	File to truncate
length	New length, should be <= current file size

Returns

int nonzero on success

ftruncate()

int ftruncate	(	int	fd,
		uint32_t	length
	)

Truncate a file to the new length.

Note

any data past the new length may not be recoverable.

Parameters

fd	file descriptor of an open file
length	New file length

Returns

int zero on success, -1 on error

init_filesystem()

void init_filesystem

(

)

Initialise the filesystem This loads the DummyFS filesystem which manages the root directory until any other driver is loaded. DummyFS is a dummy and does nothing.

mkdir()

int mkdir	(	const char *	pathname,
		mode_t	mode
	)

Make a directory.

Parameters

pathname	Fully qualified pathname
mode	UNIX permission mode, ignored

Returns

int zero on success, -1 on error

read_storage_device()

int read_storage_device	(	const char *	name,
		uint64_t	start_block,
		uint32_t	bytes,
		unsigned char *	data
	)

Read blocks from storage device by name.

Parameters

name	Name of storage device registered by register_storage_device()
start_block	Starting block number
bytes	Number of bytes to read (should be modulus of block size)
data	Buffer to receive read data

Returns

int nonzero on success

register_filesystem()

int register_filesystem

(

filesystem_t *

newfs

)

Register a new filesystem.

Parameters

newfs

Pointer to new filesystem information to register

Returns

int nonzero on success

register_storage_device()

int register_storage_device

(

storage_device_t *

newdev

)

Register a new storage device.

Parameters

newdev

New storage device information to register

Returns

int nonzero on success

rmdir()

int rmdir

(

const char *

pathname

)

Remove a directory.

Parameters

pathname

Fully qualified pathname

Returns

int zero on success, -1 on error

unlink()

int unlink

(

const char *

pathname

)

Delete a file (not a directory)

Parameters

pathname

Fully qualified pathname

Returns

int zero on success, -1 on error

write_storage_device()

int write_storage_device	(	const char *	name,
		uint64_t	start_block,
		uint32_t	bytes,
		const unsigned char *	data
	)

Write blocks to storage device by name.

Parameters

name	Name of storage device registered by register_storage_device()
start_block	Starting block number
bytes	Number of bytes to write (should be modulus of block size)
data	Data to write

Returns

int nonzero on success