VFS (Virtual File System)

KOS contains a reasonably capable VFS (virtual file system), much like a *nix. It provides the basic file operations which you have come to expect as a programmer: open (with path translation, thus the ``virtual'' part of VFS), read, write, seek, tell, readdir, ioctl, rename, unlink, mmap. VFS also provides an unconventional but very helpful function, total, which returns the total file size if possible. Some of these functions may not work on all file systems. For example, you cannot write to a CD or a ROMFS image. But you can write to a VMU on a DC. You also cannot mmap on most file systems, the notable exceptions being fs_romdisk and fs_vmu. Failure in these functions is indicated (as mentioned above) by a negative return value, except in the case of open, which may eventually be changed to conform anyway.

file_t fs_open(const char * fn, int mode)

Opens a file on the VFS. This function searches its VFS table for the longest match against the first of fn, and then passes off the rest of the functionality to the given VFS with the remainder of the path. The returned value should be considered opaque and will be zero (or NULL if you prefer) on error, or a valid file handle otherwise. The mode parameter should be one of O_RDONLY, O_RDWR, O_APPEND, or O_WRONLY, potentially logically or'd with O_TRUNC, O_DIR, or O_META.

void fs_close(file_t hnd)

Closes an opened VFS file. Handle values passed to this function (and all other VFS functions below) are not checked for validity! If you try to pass an already closed handle (or a random value) to this function, the result will be undefined.

ssize_t fs_read(file_t hnd, void * buffer, size_t cnt)

Reads up to cnt bytes from the file handle hnd, and stores them into buffer. The actual number of read bytes will be returned.

ssize_t fs_write(file_t hnd, const void * buffer, size_t cnt)

Writes up to cnt bytes from buffer and stores them to the file handle hnd. The actual number of written bytes will be returned.

off_t fs_seek(file_t hnd, off_t offset, int whence)

Works like the ANSI fseek function. The file pointed to by hnd will be seeked to offset, where offset is interpreted as specified in whence. The actual file position will be returned. The whence parameter is one of SEEK_SET, SEEK_CUR, or SEEK_END.

off_t fs_tell(file_t hnd)

Returns the file position of the handle hnd.

size_t fs_total(file_t hnd)

Returns the total byte size of the handle hnd, if applicable.

dirent_t * fs_readdir(file_t hnd)

Reads the next directory entry from the handle hnd. The file handle is assumed to have been opened using fs_open(..., O_DIR). The returned pointer may be queried for values unless it is NULL, which signifies the end of the directory listing.

int fs_ioctl(file_t hnd, void * data, size_t size)

Perform a device/fs specific I/O Control message on the given file handle. This is entirely fs dependent. The only existing fs handler which supports this ioctl is fs_iso9660, which uses it to hint that the data/index cache should be flushed and the CD TOC should be rescanned.

int fs_rename(const char * fn1, const char * fn2)

Move/rename a file, if possible. The two files must be located on the same file system. Returns a negative value on failure.

int fs_unlink(const char * fn)

Delete a file, if possible. Returns a negative value on failure.

int fs_chdir(const char * fn)

Change the working directory for the current thread. Any relative path (i.e., a path not beginning with ``/'') will be treated as relative to this directory. This value will be inherited by any thread created by the thread which called this function. Returns a negative value on failure.

void * fs_mmap(file_t hnd)

Returns a pointer to a buffer containing the full data of the handle hnd. Depending on how the file was opened, the buffer may or may not be writable. This call may not succeed (limited memory, inability of the file system to perform the call, etc). In this case, the function will return NULL.

const char * fs_getwd()

Returns the working directory for the current thread.

int fs_handler_add(const char * prefix, vfs_handler * hnd)

Adds a new VFS handler to the VFS system. Each of the built-in file systems performs this call on startup. The file system will be placed on the file heirarchy at prefix, and will be accessed using the functions pointed to by hnd. Since this is considered an arcane and fairly internal piece of the VFS, please look at the source code for an existing handler if you wish to write a new one. It is fairly simple but beyond the scope of this document.

int fs_handler_remove(const vfs_handler * hnd)

Removes a previously added VFS handler. Each built-in file system performs this call on shutdown.