Filesystem API Tutorial

This tutorial will guide you through the steps that are necessary to work with files on the standard HelenOS API level in an idiomatic way.

Preparing to use the API

HelenOS filesystem API is implemented in the standard library, so there is no need to link against any additional library in order to be able to use it. HelenOS only requires filesystem clients to include vfs/vfs.h in order to get declarations of all the APIs:

#include <vfs/vfs.h>

Paths and File handles

The API is designed to use file handles as a primary and prefered way to refer to files. One may obtain a file handle by looking up a filesytem path, creating a new file or directory or attaching a new filesystem into the filesystem hierarchy.

Reading an existing file

Suppose we want to read the contents of file /foo/bar. We first need to lookup the file and convert it to a file handle:

int file = vfs_lookup("/foo/bar", WALK_REGULAR);
if (file < 0)
        return file;

This will only succeed if the file exists and is a regular file, i.e. not a directory, in which case vfs_lookup() receives a file handle. Otherwise we receive a negative error code and bail out.

Because our intention is to perform a read operation on file, we must first open it for reading:

int rc = vfs_open(file, MODE_READ);
if (rc != EOK) {
        vfs_put(file);
        return rc;
}

Note that vfs_open() does not take a path as an argument and does not return a file handle. Instead it takes a pre-existing file handle as an argument, internally marks the file as open for reading and returns a result code, which is EOK on success and negative on error. Also note that in case of error, the file handle we are using needs to be returned to the system before bailing out.

We are now ready to do a couple of synchronous reads from the file. Let's say we first want to read a 4KiB-buffer from offset 0x1000:

uint8_t buffer[4096];
aoff64_t pos = 0x1000;

ssize_t size = vfs_read(file, &pos, buffer, sizeof(buffer));
if (size < 0) {
        vfs_put(file);
        return size;
}
if (size == 0) {
        /* handle EOF */
}

/* buffer is now guaranteed to contain the desired data */
...

The position to read from was passed to vfs_read() explicitly. Moreover, pos was updated by vfs_read() to reflect the updated position. We are now ready to read an additional 4KiB-buffer from offset 0x2000:

size = vfs_read(file, &pos, buffer, sizeof(buffer));
if (size < 0) {
        vfs_put(file);
        return size;
}
if (size == 0) {
        /* handle EOF */
}

/* buffer is now guaranteed to contain the desired data */
...

Finally, if we wanted to continue reading at offset 0x4000, we could simply do:

pos = 0x4000;
size = vfs_read(file, &pos, buffer, sizeof(buffer));
...

When we are finished with file, we must not forget to return it to the system:

vfs_put(file);

Creating a new directory with a file

Imagine we now want to create a new directory /foo/foobar, create a file named hello.txt and write "Hello world!" to it. Let's start with creating the directory:

int foobar;
int rc = vfs_link_path("/foo/foobar", KIND_DIRECTORY, &foobar);
if (rc != EOK)
        return rc;

vfs_link_path() used here is a convenience wrapper around vfs_link(), which we will shortly use too. It allows us not to care about /foo's handle (but directory /foo must already exist). If the return code is EOK, we can be sure that a new directory named /foo/foobar was created and also that there was no file or directory of the same name standing in its way. Moreover, the variable foobar now contains a file handle of the newly created directory. We will use it now to create the file:

int hello;
rc = vfs_link(foobar, "hello", KIND_FILE, &hello);
(void) vfs_put(foobar);
if (rc != EOK)
        return rc;

As in the previous scenario, the file handle needs to be opened before we can write to it:

rc = vfs_open(hello, MODE_WRITE);
if (rc != EOK) {
        vfs_put(hello);
        return rc;
}

Finally, we can write our message. This time we use a compound literal to pass our initial position:

char greeting[] = "Hello world!";
ssize_t size = vfs_write(hello, (aoff64_t []) {0}, greeting, sizeof(greeting));
if (size < 0) {
        vfs_put(hello);
        return size;
}

Finally, we put the file handle:

rc = vfs_put(hello);
if (rc != EOK)
        return rc;

Here we are interested in the return code of vfs_put() because we made modifications to the file. An error at this point might indicate our data didn't get entirely through.