spdos.h API Reference

The spdos.h library provides access to filesystem functions that forward to Spectranet's Virtual File System (VFS). This allows you to use standard file operations (open, read, write, etc.) with any mounted filesystem (XFS, HTTPS, TNFS, etc.).

Overview

All functions in spdos.h are thin wrappers around Spectranet ROM routines. They provide a familiar POSIX-like interface while working with Spectranet's VFS abstraction layer.

File Operations

`open`

Open a file for reading or writing.

int open(const char *name, int flags, mode_t mode);

Parameters:

name (const char*): Path to the file to open. Can be a relative path (e.g., "file.txt") or absolute path (e.g., "/path/to/file.txt"). Paths use / as the directory separator.
flags (int): File access flags. Use bitwise OR (|) to combine multiple flags:
- O_RDONLY (0x01): Open for reading only
- O_WRONLY (0x02): Open for writing only
- 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 if it exists
mode (mode_t): File permissions (currently unused, pass 0)

Returns:

On success: File handle (non-negative integer, typically 0-255)
On error: -1

Example:

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

// Open file for reading
int fd = open("data.txt", O_RDONLY, 0);
if (fd >= 0) {
    // File opened successfully
    // ... read from file ...
    close(fd);
}

// Open file for writing, create if doesn't exist
int fd2 = open("output.txt", O_WRONLY | O_CREAT | O_TRUNC, 0);

`close`

Close an open file handle.

int close(int handle);

Parameters:

handle (int): File handle returned by open()

Returns:

On success: 0
On error: -1

Example:

int fd = open("file.txt", O_RDONLY, 0);
if (fd >= 0) {
    // ... use file ...
    close(fd);  // Always close files when done
}

`read`

Read data from an open file.

ssize_t read(int handle, void *buf, size_t len);

Parameters:

handle (int): File handle returned by open()
buf (void*): Buffer to store read data
len (size_t): Maximum number of bytes to read

Returns:

On success: Number of bytes read (0 indicates end of file)
On error: -1

Note: The function may read fewer bytes than requested. Always check the return value to determine how many bytes were actually read.

Example:

int fd = open("data.bin", O_RDONLY, 0);
if (fd >= 0) {
    unsigned char buffer[256];
    ssize_t bytes_read = read(fd, buffer, sizeof(buffer));
    if (bytes_read > 0) {
        // Process buffer[0..bytes_read-1]
    } else if (bytes_read == 0) {
        // End of file
    } else {
        // Error occurred
    }
    close(fd);
}

`write`

Write data to an open file.

ssize_t write(int handle, void *buf, size_t len);

Parameters:

handle (int): File handle returned by open() (must be opened with O_WRONLY or O_RDWR)
buf (void*): Buffer containing data to write
len (size_t): Number of bytes to write

Returns:

On success: Number of bytes written (should equal len unless an error occurred)
On error: -1

Note: The function may write fewer bytes than requested. Always check the return value to ensure all data was written.

Example:

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

`readbyte`

Read a single byte from an open file.

int readbyte(int fd);

Parameters:

fd (int): File handle returned by open()

Returns:

On success: Byte value (0-255)
On end of file: -1
On error: -1

Example:

int fd = open("file.txt", O_RDONLY, 0);
if (fd >= 0) {
    int byte;
    while ((byte = readbyte(fd)) >= 0) {
        // Process byte
    }
    close(fd);
}

`writebyte`

Write a single byte to an open file.

int writebyte(int handle, int c);

Parameters:

handle (int): File handle returned by open() (must be opened with O_WRONLY or O_RDWR)
c (int): Byte value to write (only the low 8 bits are used)

Returns:

On success: 0
On error: -1

Example:

int fd = open("output.bin", O_WRONLY | O_CREAT | O_TRUNC, 0);
if (fd >= 0) {
    for (int i = 0; i < 256; i++) {
        writebyte(fd, i);
    }
    close(fd);
}

`lseek`

Change the file position (seek) in an open file.

long lseek(int fd, long posn, int whence);

Parameters:

fd (int): File handle returned by open()
posn (long): Offset in bytes
whence (int): Reference point for the offset:
- SEEK_SET (0): Beginning of file
- SEEK_CUR (1): Current position
- SEEK_END (2): End of file

Returns:

On success: New file position (offset from beginning of file)
On error: -1

Example:

int fd = open("file.bin", O_RDONLY, 0);
if (fd >= 0) {
    // Seek to offset 1024 from beginning
    long pos = lseek(fd, 1024, SEEK_SET);
    if (pos >= 0) {
        // Read from position 1024
        unsigned char buffer[256];
        read(fd, buffer, sizeof(buffer));
    }
    close(fd);
}

Directory Operations

`mkdir`

Create a new directory.

int mkdir(char *name);

Parameters:

name (char*): Path to the directory to create. Can be a relative path (e.g., "newdir") or absolute path (e.g., "/path/to/newdir"). Parent directories must already exist.

Returns:

On success: 0
On error: -1

Example:

if (mkdir("mydir") == 0) {
    printf("Directory created\n");
} else {
    printf("Failed to create directory\n");
}

`rmdir`

Remove an empty directory.

int rmdir(char *name);

Parameters:

name (char*): Path to the directory to remove. The directory must be empty.

Returns:

On success: 0
On error: -1

Example:

if (rmdir("mydir") == 0) {
    printf("Directory removed\n");
} else {
    printf("Failed to remove directory\n");
}

`chdir`

Change the current working directory.

int chdir(char *name);

Parameters:

name (char*): Path to the directory to change to. Can be:
- Relative path: "subdir", "../parent"
- Absolute path: "/", "/path/to/dir"
- Special paths: "." (current directory), ".." (parent directory)

Returns:

On success: 0
On error: -1

Example:

chdir("/");           // Change to root directory
chdir("games");       // Change to subdirectory
chdir("../other");    // Change to sibling directory
chdir("..");          // Change to parent directory

`getcwd`

Get the current working directory path.

char *getcwd(char *buf, size_t buflen);

Parameters:

buf (char*): Buffer to store the current directory path
buflen (size_t): Size of the buffer in bytes

Returns:

On success: Pointer to buf (same as buf parameter)
On error: NULL (buffer too small or error occurred)

Example:

char cwd[256];
if (getcwd(cwd, sizeof(cwd)) != NULL) {
    printf("Current directory: %s\n", cwd);
} else {
    printf("Failed to get current directory\n");
}

File Management

`rename`

Rename or move a file or directory.

int rename(const char *s, const char *d);

Parameters:

s (const char*): Source path (current name/location)
d (const char*): Destination path (new name/location)

Returns:

On success: 0
On error: -1

Example:

// Rename a file
rename("oldname.txt", "newname.txt");

// Move a file to a different directory
rename("file.txt", "subdir/file.txt");

`remove`

Delete a file.

int remove(char *name);

Parameters:

name (char*): Path to the file to delete

Returns:

On success: 0
On error: -1

Note: This function is equivalent to unlink().

Example:

if (remove("file.txt") == 0) {
    printf("File deleted\n");
}

`unlink`

Delete a file (same as remove).

int unlink(char *name);

Parameters:

name (char*): Path to the file to delete

Returns:

On success: 0
On error: -1

Example:

unlink("file.txt");

Directory Reading

`opendir`

Open a directory for reading.

int opendir(char *name);

Parameters:

name (char*): Path to the directory to open. Can be:
- "." - Current directory
- "subdir" - Subdirectory name
- "/" - Root directory
- Any valid directory path

Returns:

On success: Directory handle (non-negative integer)
On error: -1

Example:

int dir = opendir(".");
if (dir >= 0) {
    // Directory opened successfully
    // ... read entries ...
    closedir(dir);
}

`readdir`

Read the next entry from an open directory.

int readdir(int dirhandle, void *buf);

Parameters:

dirhandle (int): Directory handle returned by opendir()
buf (void*): Buffer to store the directory entry. Must be at least 256 bytes. The entry name is stored as a null-terminated string.

Returns:

On success: 0 (entry read into buffer)
On end of directory: -1 (no more entries)
On error: -1

Note: The buffer contains the entry name as a null-terminated string. To determine if an entry is a file or directory, use stat() or isdir().

Example:

int dir = opendir(".");
if (dir >= 0) {
    char entry[256];
    while (readdir(dir, entry) == 0) {
        printf("Entry: %s\n", entry);
    }
    closedir(dir);
}

`closedir`

Close an open directory handle.

int closedir(int dirhandle);

Parameters:

dirhandle (int): Directory handle returned by opendir()

Returns:

On success: 0
On error: -1

Example:

int dir = opendir(".");
if (dir >= 0) {
    // ... read entries ...
    closedir(dir);  // Always close directories when done
}

File Status

`stat`

Get file or directory information.

int stat(const char *path, struct stat *buf);

Parameters:

path (const char*): Path to the file or directory
buf (struct stat*): Buffer to store file information. Must be at least 256 bytes. The struct stat structure contains:
- st_mode (at offset 0): File mode flags
  - S_IFDIR (0x4000): Directory
  - S_IFREG (0x8000): Regular file
- st_size: File size in bytes
- Other fields: Access/modification times, user/group IDs

Returns:

On success: 0 (information stored in buf)
On error: -1

Example:

#include <sys/stat.h>

struct stat st;
if (stat("file.txt", &st) == 0) {
    if (st.st_mode & S_IFDIR) {
        printf("Is a directory\n");
    } else if (st.st_mode & S_IFREG) {
        printf("Is a file, size: %lu bytes\n", st.st_size);
    }
}

`isdir`

Check if a path is a directory.

int isdir(const char *path);

Parameters:

path (const char*): Path to check

Returns:

1 if path is a directory
0 if path is not a directory or doesn't exist

Example:

if (isdir("mydir")) {
    printf("mydir is a directory\n");
} else {
    printf("mydir is not a directory or doesn't exist\n");
}

Mount Operations

`mount`

Mount a filesystem at the specified mount point.

int mount(int mount_point, char* password, char* user_id, char* path, char* hostname, char *protocol);

Parameters:

mount_point (int): Mount point number (0-3). Each mount point can have one filesystem mounted.
password (char*): Password string for authentication. Can be NULL for anonymous access.
user_id (char*): User ID string for authentication. Can be NULL for anonymous access.
path (char*): Mount source path. Examples:
- "ram" - For XFS RAM filesystem
- "/test/https" - For HTTPS filesystem path
- "/home/tnfs" - For TNFS filesystem path
hostname (char*): Hostname or server address. Examples:
- "ram" - For local filesystems (XFS)
- "spectranext.net" - For HTTPS filesystem
- "tnfs.server.local" - For TNFS server
protocol (char*): Protocol name. Must be one of:
- "xfs" - XFS local filesystem
- "https" - HTTPS web-based filesystem
- "tnfs" - TNFS network filesystem

Returns:

On success: 0
On error: -1 (mount point already in use, protocol not recognized, or mount failed)

Example:

// Mount XFS RAM filesystem at mount point 0
mount(0, NULL, NULL, "ram", NULL, "xfs");

// Mount HTTPS filesystem at mount point 1
mount(1, NULL, NULL, "/test/https", "spectranext.net", "https");

// Mount TNFS with authentication
mount(2, "mypassword", "myuser", "/home/tnfs", "tnfs.server.local", "tnfs");

`umount`

Unmount a filesystem from the specified mount point.

int umount(int mount_point);

Parameters:

mount_point (int): Mount point number (0-3) to unmount

Returns:

On success: 0
On error: -1 (mount point not mounted or error occurred)

Example:

// Unmount mount point 1
umount(1);

`setmountpoint`

Set the active mount point for file operations.

int setmountpoint(int mount_point);

Parameters:

mount_point (int): Mount point number (0-3) to make active

Returns:

On success: 0
On error: -1 (mount point > 3 or not mounted)

Note: All subsequent file operations (open, readdir, etc.) will use this mount point until changed.

Example:

// Mount HTTPS at mount point 1
mount(1, NULL, NULL, "/files", "example.com", "https");

// Switch to mount point 1
setmountpoint(1);

// Now file operations use mount point 1
int fd = open("file.txt", O_RDONLY, 0);  // Opens from mount point 1

`getmountpoint`

Get the current active mount point.

int getmountpoint(void);

Parameters:

None

Returns:

Current mount point number (0-3)

Example:

int current = getmountpoint();
printf("Current mount point: %d\n", current);

Constants

File Mode Flags

These constants are used with stat() to check file type:

S_IFDIR (0x4000): Directory bit flag
S_IFREG (0x8000): Regular file bit flag

Example:

#include <sys/stat.h>

struct stat st;
if (stat("path", &st) == 0) {
    if (st.st_mode & S_IFDIR) {
        // It's a directory
    } else if (st.st_mode & S_IFREG) {
        // It's a regular file
    }
}

Error Handling

All functions return -1 on error. To get more detailed error information, check the return values:

File operations (open, read, write): Return -1 on error
Directory operations (opendir, readdir): Return -1 on error or end of directory
Mount operations (mount, umount): Return -1 on error

Overview​

File Operations​

open​

close​

read​

write​

readbyte​

writebyte​

lseek​

Directory Operations​

mkdir​

rmdir​

chdir​

getcwd​

File Management​

rename​

remove​

unlink​

Directory Reading​

opendir​

readdir​

closedir​

File Status​

stat​

isdir​

Mount Operations​

mount​

umount​

setmountpoint​

getmountpoint​

Constants​

File Mode Flags​

Error Handling​

Overview

File Operations

`open`

`close`

`read`

`write`

`readbyte`

`writebyte`

`lseek`

Directory Operations

`mkdir`

`rmdir`

`chdir`

`getcwd`

File Management

`rename`

`remove`

`unlink`

Directory Reading

`opendir`

`readdir`

`closedir`

File Status

`stat`

`isdir`

Mount Operations

`mount`

`umount`

`setmountpoint`

`getmountpoint`

Constants

File Mode Flags

Error Handling