Filesystem Operations

SYS_OPEN

Open a file or device and return a file descriptor. Syscall Number: 6

Parameters

path

const char*

required

Path to the file or device to open (e.g., “/dev/tty”, “/home/user/file.txt”)

flags

int

Open flags (currently stored but not enforced)

Returns

return

int

On success: file descriptor (0-31)
On error: -1 (file not found or no free fd slots)

Behavior

Resolves the path using vfs_resolve()
Searches the process’s fd table for an unused entry
Marks the entry as in-use and associates it with the VFS node
Sets the file offset to 0
Returns the fd index

File descriptors 0, 1, and 2 are pre-allocated for stdin, stdout, and stderr during process creation.

Example

int fd = open_syscall("/tmp/test.txt", 0);
if (fd >= 0) {
    // Use fd for read/write operations
    close_syscall(fd);
}

SYS_CLOSE

Close a file descriptor and release associated resources. Syscall Number: 7

Parameters

int

required

File descriptor to close

Returns

return

int

On success: 0
On error: -1 (invalid fd or not in use)

Behavior

Marks the fd table entry as unused and clears the VFS node pointer. If the fd is associated with a pipe, the pipe may be released when both ends are closed.

Example

close_syscall(3);

SYS_READ

Read bytes from a file descriptor into a buffer. Syscall Number: 8

Parameters

int

required

File descriptor to read from

buf

void*

required

Buffer to store read data

count

size_t

required

Maximum number of bytes to read

Returns

return

ssize_t

On success: number of bytes read (may be less than count)
On end-of-file: 0
On error: -1

Behavior

The implementation delegates to either:

Pipe: pipe_read() for IPC pipes (stored in fd_entry.fs_priv)
VFS: vfs_read() for regular files and devices

After a successful read, the file offset is advanced by the number of bytes read.

Implementation

case SYS_READ: {
    int fd = (int)arg1;
    struct fd_entry *fde = &procs[current_pid].fd_table[fd];
    
    if (fde->fs_priv) {
        // Pipe read
        return (uint64_t)pipe_read((struct pipe *)fde->fs_priv, 
                                   (void *)arg2, (size_t)arg3);
    }
    
    // VFS read
    int n = vfs_read(fde->vfs_node, fde->offset, (void *)arg2, (size_t)arg3);
    if (n > 0) fde->offset += n;
    return (uint64_t)n;
}

Example

char buffer[256];
int n = read_syscall(fd, buffer, sizeof(buffer));
if (n > 0) {
    // Process n bytes in buffer
}

SYS_WRITE

Write bytes from a buffer to a file descriptor. Syscall Number: 1

Parameters

int

required

File descriptor to write to

buf

const void*

required

Buffer containing data to write

count

size_t

required

Number of bytes to write

Returns

return

ssize_t

On success: number of bytes written
On error: -1

Behavior

Delegates to:

Pipe: pipe_write() if the fd is associated with a pipe
VFS: vfs_write() for regular files
Fallback: Direct VGA output for early boot before VFS is initialized

Example

const char *msg = "Hello, world!\n";
write_syscall(1, msg, 14);  // Write to stdout

SYS_STAT

Get file status information by path. Syscall Number: 9

Parameters

path

const char*

required

Path to the file

statbuf

struct vfs_stat*

required

Pointer to stat structure to fill

Returns

return

int

On success: 0
On error: -1 (file not found)

vfs_stat Structure

struct vfs_stat {
    uint64_t inode;
    uint64_t size;
    int      type;    // VFS_FILE or VFS_DIR
    int      mode;    // Unix permissions (e.g., 0755)
    int      nlink;   // Number of hard links
};

Example

struct vfs_stat st;
if (stat_syscall("/home/user/file.txt", &st) == 0) {
    printf("Size: %lu bytes\n", st.size);
}

SYS_FSTAT

Get file status information by file descriptor. Syscall Number: 34

Parameters

int

required

File descriptor

statbuf

struct vfs_stat*

required

Pointer to stat structure to fill

Returns

return

int

On success: 0
On error: -1 (invalid fd or no VFS node)

SYS_LSEEK

Reposition the file offset for a file descriptor. Syscall Number: 33

Parameters

int

required

File descriptor

offset

int64_t

required

Offset value (interpretation depends on whence)

whence

int

required

0 (SEEK_SET): Set offset to offset
1 (SEEK_CUR): Set offset to current position + offset
2 (SEEK_END): Set offset to file size + offset

Returns

return

int64_t

On success: new file offset
On error: -1

Example

// Seek to beginning
lseek_syscall(fd, 0, 0);

// Seek to end
lseek_syscall(fd, 0, 2);

// Seek forward 100 bytes
lseek_syscall(fd, 100, 1);

SYS_GETDENTS

Read directory entries from an open directory file descriptor. Syscall Number: 10

Parameters

int

required

File descriptor for an open directory

index

uint32_t

required

Index of the directory entry to read (0-based)

buf

char*

required

Buffer to store the entry name (null-terminated string)

Returns

return

int

On success: 1 (entry found and copied)
At end of directory: 0
On error: -1

Behavior

Calls vfs_readdir() to get the VFS node for the child at the given index, then copies the child’s name to the user buffer.

Example

int fd = open_syscall("/home", 0);
if (fd >= 0) {
    char name[256];
    for (int i = 0; ; i++) {
        int ret = getdents_syscall(fd, i, name);
        if (ret == 0) break;  // End of directory
        if (ret > 0) {
            printf("Entry: %s\n", name);
        }
    }
    close_syscall(fd);
}

SYS_MKDIR

Create a new directory. Syscall Number: 11

Parameters

path

const char*

required

Path of the directory to create (e.g., “/tmp/newdir”)

Returns

return

int

On success: 0
On error: -1

Behavior

Current implementation only supports creating directories under the root (”/”). The leading ”/” is stripped before calling vfs_mkdir().

SYS_UNLINK

Remove a file or directory entry. Syscall Number: 12

Parameters

path

const char*

required

Path to the file to remove

Returns

return

int

On success: 0
On error: -1

SYS_GETCWD

Get the current working directory. Syscall Number: 17

Parameters

buf

char*

required

Buffer to store the path

size

size_t

required

Size of the buffer

Returns

return

char*

On success: pointer to buf (same as arg1)
On error: -1

Behavior

Aurora OS currently does not maintain per-process working directories. This syscall always returns ”/” (root directory).

buf[0] = '/';
buf[1] = '\0';
return arg1;

SYS_IOCTL

Perform device-specific control operations. Syscall Number: 36

Parameters

int

required

File descriptor

request

int

required

Device-specific request code

argp

void*

Request-specific argument pointer

Returns

return

int

On success: 0
On error: -1

Supported Requests

TIOCGWINSZ (0x5413)

Get terminal window size.

struct winsize {
    uint16_t ws_row;     // 24 (hardcoded)
    uint16_t ws_col;     // 80 (hardcoded)
    uint16_t ws_xpixel;  // 0
    uint16_t ws_ypixel;  // 0
};

Example

struct winsize ws;
if (ioctl_syscall(1, 0x5413, &ws) == 0) {
    printf("Terminal: %dx%d\n", ws.ws_col, ws.ws_row);
}

System Calls

Kernel API

Package Manager

​SYS_OPEN

​Parameters

​Returns

​Behavior

​Example

​SYS_CLOSE

​Parameters

​Returns

​Behavior

​Example

​SYS_READ

​Parameters

​Returns

​Behavior

​Implementation

​Example

​SYS_WRITE

​Parameters

​Returns

​Behavior

​Example

​SYS_STAT

​Parameters

​Returns

​vfs_stat Structure

​Example

​SYS_FSTAT

​Parameters

​Returns

​SYS_LSEEK

​Parameters

​Returns

​Example

​SYS_GETDENTS

​Parameters

​Returns

​Behavior

​Example

​SYS_MKDIR

​Parameters

​Returns

​Behavior

​SYS_UNLINK

​Parameters

​Returns

​SYS_GETCWD

​Parameters

​Returns

​Behavior

​SYS_IOCTL

​Parameters

​Returns

​Supported Requests

​TIOCGWINSZ (0x5413)

​Example

Build docs developers (and LLMs) love

SYS_OPEN

Parameters

Returns

Behavior

Example

SYS_CLOSE

Parameters

Returns

Behavior

Example

SYS_READ

Parameters

Returns

Behavior

Implementation

Example

SYS_WRITE

Parameters

Returns

Behavior

Example

SYS_STAT

Parameters

Returns

vfs_stat Structure

Example

SYS_FSTAT

Parameters

Returns

SYS_LSEEK

Parameters

Returns

Example

SYS_GETDENTS

Parameters

Returns

Behavior

Example

SYS_MKDIR

Parameters

Returns

Behavior

SYS_UNLINK

Parameters

Returns

SYS_GETCWD

Parameters

Returns

Behavior

SYS_IOCTL

Parameters

Returns

Supported Requests

TIOCGWINSZ (0x5413)

Example