Skip to main content

XFS Filesystem

Viewing XFS Files in Browser

Files stored in the local XFS filesystem can be viewed and managed live in your web browser using the Spectranext File Browser. Simply connect your device via USB and select it from the device picker to browse, upload, download, commit to flash, and manage files directly from your browser.

See Syncing with Computer for more details.

XFS is Spectranext's local filesystem that provides access to onboard storage directly from Spectrum programs. It combines a 4MB temporary RAM filesystem with a 4MB overlayed flash filesystem. Files uploaded from your computer go to RAM first for fast iteration; files committed to flash remain available after power loss.

Spectranext BASIC shorthand

In Spectranext BASIC, %mount "<url>" is a simplified form that mounts into a free slot and switches %fs to it automatically. This shorthand is specific to SpectraNext and is not available on the original Spectranet.

If you need BASIC compatibility with Spectranet, or you want to force a particular slot such as %mount 0, "xfs://ram/", use the full form with an explicit mount number.

Overview​

XFS provides:

  • Local Filesystem Access: Access files stored in Spectranext's RAM and committed flash layers
  • 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 over USB, access them from Spectrum programs, and commit selected files to flash when they should persist

The filesystem is overlayed: flash-backed files and RAM-backed files appear in the same directory tree. There is no separate flash mount and no special permanent-storage folder. Reads prefer flash when a file exists in both layers. New files are written to RAM by default; writes to paths that already exist in flash update the flash-backed file. Use Commit To Flash in the Browser or spx commit <path> from the SDK when you want a RAM file to become permanent. Deletes remove the path from both layers.

See Overlayed Filesystem for the detailed layer rules and commit workflow.

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.

Best practice

Before mounting into a slot, it is best practice to unmount that slot first with %umount <slot> or umount(slot).

Mounting Local XFS​

The local XFS filesystem is mounted using the protocol "xfs://ram/". The hostname remains "ram" for compatibility, even though committed flash files are visible through the same mount:

#include <spdos.h>

mount(0, NULL, NULL, "", "ram", "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: Default local XFS filesystem (xfs://ram/) on Spectranext
  • Mount Point 1: Often used when loading Spectranext programs from HTTPS
  • Mount Point 2: Spare additional mount when needed
  • Mount Point 3: Preferred for business and application-level mounts (HTTP(s), TNFS, external resources)

See Filesystem overview: mount points for details.

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", "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​

  • Limited Handles: Maximum 4 open files/directories simultaneously
  • File Size: Limited by the available space in the active storage layer
  • Write Semantics: Normal file writes go to RAM first; commit files or directories to flash when they should persist
  • Persistence: RAM-only files are cleared on power loss, while committed flash files survive

Next Steps​