Retro Rocket Kernel BASIC-Powered Operating System

Data Structures | Macros | Typedefs | Enumerations | Functions
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