Skip to main content

XFS Filesystem

XFS is Spectranext's local filesystem that provides access to RAM-based storage directly from Spectrum programs. It allows you to transfer files from your computer and access them from your Spectrum programs.

Overview​

XFS provides:

  • RAM Filesystem Access: Access files stored in Spectranext's RAM filesystem
  • Standard VFS Interface: Uses Spectranet's standard VFS (Virtual File System) API with xfs:// prefix
  • File Operations: Read, write, list, create, delete files and directories with standard Spectranet BASIC commands
  • Development Workflow: Transfer files via USBFS, access from Spectrum programs

Mounting XFS​

To use XFS, you must first mount it. XFS uses the protocol name "xfs" and a hostname to specify which filesystem to mount.

Mounting RAM Filesystem​

The RAM filesystem is mounted using the protocol "xfs://ram/":

#include <spdos.h>

mount(0, NULL, NULL, "ram", NULL, "xfs");

Keep in mind, that mounting can be happen automatically upon boot.

Unmounting​

umount(0);

Mount Points​

Spectranet supports up to 4 mount points (0-3). Each mount point can have a different filesystem mounted:

  • Mount Point 0: Typically used for primary filesystem
  • Mount Points 1-3: Available for additional filesystems

You can switch between filesystems using:

setmountpoint(0);  // Switch to filesystem 0

Accessing Files from Spectrum​

Once XFS is mounted, you can access files using standard Spectranet VFS operations.

Opening Files​

#include <spdos.h>
#include <fcntl.h>

int fd = open("program.tap", O_RDONLY, 0);  // Open for reading
int fd2 = open("output.txt", O_WRONLY | O_CREAT | O_TRUNC, 0);  // Open for writing

File Flags:

  • O_RDONLY (0x01) - Open for reading
  • O_WRONLY (0x02) - Open for writing
  • O_RDWR (0x03) - Open for reading and writing
  • O_CREAT (0x04) - Create file if it doesn't exist
  • O_TRUNC (0x08) - Truncate file to zero length

Reading Files​

#include <spdos.h>
#include <fcntl.h>
#include <unistd.h>

int fd = open("program.tap", O_RDONLY, 0);
if (fd >= 0) {
    unsigned char buffer[256];
    ssize_t bytes_read;
    while ((bytes_read = read(fd, buffer, sizeof(buffer))) > 0) {
        // Process buffer
    }
    close(fd);
}

Writing Files​

#include <spdos.h>
#include <fcntl.h>
#include <unistd.h>

int fd = open("output.txt", O_WRONLY | O_CREAT | O_TRUNC, 0);
if (fd >= 0) {
    const char* data = "Hello, world!\nLine 2\n";
    write(fd, data, strlen(data));
    close(fd);
}

Closing Files​

close(fd);

Important: Always close files when done to free resources.

Listing Directories​

#include <spdos.h>
#include <dirent.h>

DIR* dir = opendir(".");
if (dir) {
    struct dirent* entry;
    while ((entry = readdir(dir)) != NULL) {
        // Process entry->d_name
    }
    closedir(dir);
}

Changing Directory​

#include <spdos.h>
#include <unistd.h>

chdir("/");              // Change to root directory
chdir("games");          // Change to subdirectory
chdir("/programs/basic"); // Change to specific path
chdir("..");             // Change to parent directory

Getting File Information​

#include <spdos.h>
#include <sys/stat.h>

struct stat st;
if (stat("filename.txt", &st) == 0) {
    // Access st.st_size, st.st_mode, etc.
}

The stat structure contains:

  • File size

Complete Examples​

Here's a complete C example that mounts XFS, lists files, and reads a file:

#include <spdos.h>
#include <fcntl.h>
#include <unistd.h>
#include <dirent.h>
#include <stdio.h>

int main(void) {
    // Mount XFS
    if (mount(0, NULL, NULL, "ram", NULL, "xfs") < 0) {
        printf("Mount failed\n");
        return -1;
    }
    
    // List directory
    DIR* dir = opendir(".");
    if (dir) {
        struct dirent* entry;
        while ((entry = readdir(dir)) != NULL) {
            printf("%s\n", entry->d_name);
        }
        closedir(dir);
    }
    
    // Open and read file
    int fd = open("data.txt", O_RDONLY, 0);
    if (fd >= 0) {
        unsigned char buffer[256];
        ssize_t bytes_read;
        while ((bytes_read = read(fd, buffer, sizeof(buffer))) > 0) {
            // Process buffer
        }
        close(fd);
    }
    
    // Unmount
    umount(0);
    return 0;
}

Limitations​

  • RAM Only: Currently only RAM filesystem is supported (hostname "ram")
  • Limited Handles: Maximum 4 open files/directories simultaneously
  • File Size: Limited by available RAM filesystem space
  • Persistence: RAM filesystem is cleared on reboot

Next Steps​