Filesystem Functions in var'aq

De'ghomjangwI'mey

F.1 Introduction

F.1.1 vfs Described

This page describes a simple filesystem extension to the var'aq programming language. It is a fairly simple scheme that gives little or no thought to the intricacies of security on a var'aq-based system; its primary functions are limited to creating, reading, writing, and appending files and it makes no pretensions of being a production-quality filesystem.

Certain non-Earthly features do exist, however; there is no concept of a file descriptor inherent in the design. File reads and writes are done by copying text data (no binary data at this stage) into and out of strings. (A close equivalent to a file descriptor in vfs would be a variable with an attached pathname; this is a fairly common idiom in systems that must keep constant access to specific files, but is not explicitly a part of the filesystem.)

F.1.2 Pathnames/SammoHpongmey

This document makes frequent reference to pathnames (SammoHpongmey or beacon-names). The precise meaning of this term approximates the Earth understanding of the term, though it may also include out-of-band information such as authentication tickets and content filters.

F.1.3 vfs Error Codes

All vfs functions have basically similar error semantics. Since the system is stateless, any function that cannot find the file it's looking for will return a null pathname (SammoH Hegh, dead beacon).

F.2 Creating and Deleting Files

F.2.1 fcreate/cher_De'ghom

pathname cher_De'ghom -

Creates a file with the specified pathname.

F.2.2 flock/Doq_De'ghom

pathname Doq_De'ghom -

Restricts write access to the file at pathname to the current process. Generally used in roughly the same place as an fopen() in C, though the semantics are drastically different.

F.2.3 funlock/DoqHa'_De'ghom

pathname DoqHa'_De'ghom -

Unlocks the file at pathname. This is generally handled by the filesystem garbage collector at process termination time, but it is considered good practice to take care of it yourself, especially in an embedded environment.

F.2.4 fdelete/HoH_De'ghom

pathname HoH_De'ghom -

Removes the file at pathname.

F.3 Reading and Writing Files

F.3.1 fread/jotlh_De'ghom

pathname jotlh_De'ghom str

Copies the contents of the file at pathname into str; returns null pathname on failure.

F.3.2 fwrite/tatlh_De'ghom

str pathname tatlh_De'ghom -

Replaces the contents of the file at pathname with str.