> ## Documentation Index
> Fetch the complete documentation index at: https://kernel.mvhcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# VFS API — Virtual Filesystem Interface in MVH Kernel

> Reference for the MVH Kernel VFS API: vfs_init, vfs_chdir, vfs_pwd, vfs_list, vfs_mkdir, vfs_touch, vfs_write, vfs_read, vfs_remove. The VFS root is RAMFS.

The Virtual Filesystem (VFS) provides a unified, path-based interface over the RAMFS root mount. All filesystem operations you perform go through this layer, which resolves paths against the current working directory and dispatches calls to the underlying RAMFS driver. Using the VFS API instead of the lower-level `fs_*` functions means your code remains correct if additional filesystem backends are added in the future.

## Limits and Constants

The following compile-time constants govern the VFS and its underlying RAMFS. All values are defined in `mvh/fs.h`.

| Constant      | Value | Description                                                                  |
| ------------- | ----- | ---------------------------------------------------------------------------- |
| `FS_NAME_MAX` | `24`  | Maximum length of a single filename component, including the null terminator |
| `FS_DATA_MAX` | `256` | Maximum size of a file's content in bytes                                    |
| `FS_PATH_MAX` | `128` | Maximum length of an absolute or relative path string                        |
| `FS_LIST_MAX` | `64`  | Maximum number of entries returned by a directory listing                    |

## The `fs_entry_t` Struct

Directory listing functions populate arrays of `fs_entry_t`. Each element describes one file or subdirectory inside the listed path.

```c theme={null}
typedef struct {
    char     name[FS_NAME_MAX]; /* null-terminated filename */
    uint8_t  is_directory;      /* 1 if entry is a directory, 0 if file */
    uint16_t size;              /* content size in bytes (0 for directories) */
} fs_entry_t;
```

<ResponseField name="name" type="char[24]">
  Null-terminated filename. Maximum length is `FS_NAME_MAX - 1` (23) usable characters.
</ResponseField>

<ResponseField name="is_directory" type="uint8_t">
  Set to `1` when the entry is a directory, `0` when it is a regular file.
</ResponseField>

<ResponseField name="size" type="uint16_t">
  Content size in bytes. Always `0` for directories. For files, never exceeds `FS_DATA_MAX` (256).
</ResponseField>

***

## Functions

### `vfs_init`

Initialize the VFS layer and mount RAMFS as the root filesystem. You must call this function once, before any other `vfs_*` call.

```c theme={null}
void vfs_init(void);
```

The working directory is set to `/` after initialization.

***

### `vfs_root_type`

Return a string identifying the type of the root-mounted filesystem.

```c theme={null}
const char *vfs_root_type(void);
```

<ResponseField name="return" type="const char *">
  A pointer to a static string describing the root filesystem type. For the current release this is always `"ramfs"`.
</ResponseField>

***

### `vfs_chdir`

Change the current working directory to the given path.

```c theme={null}
int vfs_chdir(const char *path);
```

<ParamField path="path" type="const char *" required>
  Absolute or relative path of the directory to change into. Must not exceed `FS_PATH_MAX` (128) bytes including the null terminator.
</ParamField>

<ResponseField name="return" type="int">
  `0` on success, or a negative value if the path does not exist or is not a directory.
</ResponseField>

***

### `vfs_pwd`

Write the absolute path of the current working directory into a caller-supplied buffer.

```c theme={null}
int vfs_pwd(char *output, uint32_t capacity);
```

<ParamField path="output" type="char *" required>
  Buffer to receive the null-terminated path string. Must be at least `capacity` bytes.
</ParamField>

<ParamField path="capacity" type="uint32_t" required>
  Size of `output` in bytes. A value of `FS_PATH_MAX` (128) is always sufficient.
</ParamField>

<ResponseField name="return" type="int">
  `0` on success, or a negative value if `output` is `NULL` or `capacity` is too small to hold the current path.
</ResponseField>

***

### `vfs_list`

List the contents of a directory into a caller-supplied array of `fs_entry_t` structs.

```c theme={null}
int vfs_list(const char *path, fs_entry_t *entries, uint32_t capacity);
```

<ParamField path="path" type="const char *" required>
  Absolute or relative path of the directory to list.
</ParamField>

<ParamField path="entries" type="fs_entry_t *" required>
  Array of `fs_entry_t` to receive the directory entries. You should allocate at least `FS_LIST_MAX` (64) elements to guarantee all entries are captured.
</ParamField>

<ParamField path="capacity" type="uint32_t" required>
  Number of elements available in `entries`. Results are truncated to this limit if the directory contains more entries.
</ParamField>

<ResponseField name="return" type="int">
  Non-negative entry count on success, or a negative value if the path does not exist or is not a directory.
</ResponseField>

***

### `vfs_mkdir`

Create a new directory at the specified path.

```c theme={null}
int vfs_mkdir(const char *path);
```

<ParamField path="path" type="const char *" required>
  Absolute or relative path of the directory to create. The parent directory must already exist. The final component must not exceed `FS_NAME_MAX - 1` (23) characters.
</ParamField>

<ResponseField name="return" type="int">
  `0` on success, or a negative value if the parent does not exist, the name is too long, or a file or directory with that name already exists.
</ResponseField>

***

### `vfs_touch`

Create a new empty file at the specified path.

```c theme={null}
int vfs_touch(const char *path);
```

<ParamField path="path" type="const char *" required>
  Absolute or relative path of the file to create. The parent directory must already exist. The final component must not exceed `FS_NAME_MAX - 1` (23) characters.
</ParamField>

<ResponseField name="return" type="int">
  `0` on success, or a negative value if the parent does not exist, the name is too long, or an entry with that name already exists.
</ResponseField>

***

### `vfs_write`

Write or append text to an existing file.

```c theme={null}
int vfs_write(const char *path, const char *text, uint8_t append);
```

<ParamField path="path" type="const char *" required>
  Absolute or relative path of the target file. The file must already exist; call `vfs_touch` first if needed.
</ParamField>

<ParamField path="text" type="const char *" required>
  Null-terminated string to write. The resulting file content must not exceed `FS_DATA_MAX` (256) bytes.
</ParamField>

<ParamField path="append" type="uint8_t" required>
  Pass `0` to overwrite the file's existing content with `text`. Pass `1` to append `text` to whatever the file already contains.
</ParamField>

<ResponseField name="return" type="int">
  `0` on success, or a negative value if the path does not exist, the target is a directory, or the write would exceed `FS_DATA_MAX`.
</ResponseField>

***

### `vfs_read`

Read the content of a file, returning a pointer to the internal data buffer and the current size.

```c theme={null}
int vfs_read(const char *path, const char **data, uint16_t *size);
```

<ParamField path="path" type="const char *" required>
  Absolute or relative path of the file to read.
</ParamField>

<ParamField path="data" type="const char **" required>
  On success, `*data` is set to point directly into the kernel's internal file buffer. Do not free or write through this pointer.
</ParamField>

<ParamField path="size" type="uint16_t *" required>
  On success, `*size` is set to the current content length in bytes (does not include a null terminator).
</ParamField>

<ResponseField name="return" type="int">
  `0` on success, or a negative value if the path does not exist or is a directory.
</ResponseField>

***

### `vfs_remove`

Remove a file or an empty directory.

```c theme={null}
int vfs_remove(const char *path);
```

<ParamField path="path" type="const char *" required>
  Absolute or relative path of the entry to remove. Directories must be empty before they can be removed.
</ParamField>

<ResponseField name="return" type="int">
  `0` on success, or a negative value if the path does not exist, the directory is not empty, or the path resolves to the root.
</ResponseField>

***

## Example

The following example initializes the VFS, creates a directory and a file inside it, writes some text, and reads it back.

```c theme={null}
#include "mvh/vfs.h"
#include <stdint.h>

void example_vfs(void) {
    /* Initialize VFS and mount RAMFS as root */
    vfs_init();

    /* Create a directory */
    vfs_mkdir("/logs");

    /* Create an empty file inside the directory */
    vfs_touch("/logs/boot.log");

    /* Write initial content */
    vfs_write("/logs/boot.log", "kernel started\n", 0);

    /* Append a second line */
    vfs_write("/logs/boot.log", "vfs ready\n", 1);

    /* Read the content back */
    const char *data = 0;
    uint16_t size    = 0;

    if (vfs_read("/logs/boot.log", &data, &size) == 0) {
        /* data points to "kernel started\nvfs ready\n", size == 26 */
        (void)data;
        (void)size;
    }

    /* List the /logs directory */
    fs_entry_t entries[FS_LIST_MAX];
    int count = vfs_list("/logs", entries, FS_LIST_MAX);

    for (int i = 0; i < count; i++) {
        /* entries[i].name, entries[i].is_directory, entries[i].size */
        (void)entries[i];
    }
}
```

<Note>
  All VFS data lives entirely in RAM. Every file, directory, and their contents are lost when the system reboots or powers off. Do not use the VFS to persist data across boots.
</Note>