Module

std::fs::sys::unix

Unix Filesystem Syscall Layer

Thin 1:1 wrappers around POSIX filesystem syscalls, returning Result<T, Io::IoError> instead of raw errno-based error codes.

All public API lives under the Fs::Sys namespace.

Functions

Function	Wraps	Returns
`open`	`open(2)` 3-arg	`Result<i32, IoError>`
`close`	`close(2)`	`Result<void, IoError>`
`read`	`read(2)`	`Result<i64, IoError>`
`write`	`write(2)`	`Result<i64, IoError>`
`lseek`	`lseek(2)`	`Result<i64, IoError>`
`stat`	`stat(2)`	`Result<Stat, IoError>`
`fstat`	`fstat(2)`	`Result<Stat, IoError>`
`lstat`	`lstat(2)`	`Result<Stat, IoError>`
`realpath`	`realpath(3)`	`Result<String, IoError>`
`tempDirPath`	env/stat fallback	`Result<String, IoError>`
`mkdir`	`mkdir(2)`	`Result<void, IoError>`
`unlink`	`unlink(2)`	`Result<void, IoError>`
`rmdir`	`rmdir(2)`	`Result<void, IoError>`
`removeDirAll`	runtime helper	`Result<void, IoError>`
`rename`	`rename(2)`	`Result<void, IoError>`
`opendir`	`opendir(3)`	`Result<DirPtr, IoError>`
`readdir`	`readdir(3)`	`Result<Option<SysDirEntry>, IoError>`
`readdirEntry`	runtime helper	`Result<boolean, IoError>`
`closedir`	`closedir(3)`	`void`

Types

Type	Description
`Stat`	File metadata: dev, ino, mode, nlink, uid, gid, size, times
`SysDirEntry`	Directory entry: name (borrowed `str`), ino, fileType

Constants

Group	Constants
Open flags	`O_RDONLY`, `O_WRONLY`, `O_RDWR`, `O_CREAT`, `O_TRUNC`, …
Seek modes	`SEEK_SET`, `SEEK_CUR`, `SEEK_END`
File type mask	`S_IFMT`, `S_IFREG`, `S_IFDIR`, `S_IFLNK`
Permission bits	`S_IRWXU`, `S_IRUSR`, `S_IWUSR`, … (user/group/other)
Dirent types	`DT_UNKNOWN`, `DT_REG`, `DT_DIR`, `DT_LNK`

Design Notes

Functions that succeed without a meaningful value (close, mkdir, etc.) return Result<void, Io::IoError> with Result::OK(()).

C Runtime Dependency

Six functions live in C (std/runtime/internal/rt_fs.c) because they cannot be expressed in pure Ignis today:

C function	Why C is needed
`ignis_stat_call`	`struct stat` layout is platform-dependent
`ignis_fstat_call`	same
`ignis_lstat_call`	same
`ignis_open3`	`open(2)` is variadic; Ignis has no variadic calls
`ignis_readdir_call`	`struct dirent` layout is platform-dependent
`ignis_remove_dir_all_call`	symlink-safe recursion uses libc structs

Everything else (read, write, close, lseek, unlink, rmdir, rename, mkdir, opendir, closedir, readdir, realpath) calls libc directly through Ignis extern blocks.

When @platform / @target / @feature attributes land, the C helpers can be replaced with platform-conditional Ignis code.

Example

import Fs from "std::fs";
import Io from "std::io";

function main(): i32 {
  let fd: Result<i32, Io::IoError> = Fs::Sys::open(
    "/tmp/test.txt",
    Fs::Sys::O_WRONLY | Fs::Sys::O_CREAT | Fs::Sys::O_TRUNC,
    438,  // 0o666
  );
  if fd.isError() { return 1; }

  let rawFd: i32 = fd.unwrap();
  let msg: *u8 = "hello from Ignis\n";
  let n: Result<i64, Io::IoError> = Fs::Sys::write(rawFd, msg as *mut void, 17);
  Fs::Sys::close(rawFd);
  return 0;
}

namespace __fs_dir

Functions

function closedir(dirp: *mut void): i32

POSIX closedir; closes a directory stream.

function opendir(name: *u8): *mut void

POSIX opendir; opens a directory stream.

function readdir(dirp: *mut void): *mut void

POSIX readdir; returns a host-owned dirent pointer or null.

namespace __fs_errno

Functions

function strerror(errnum: i32): *u8

Returns a host-owned message for an errno value.

Constants

const EACCES: i32

const EAGAIN: i32

const EEXIST: i32

const EINTR: i32

const EINVAL: i32

const ENOENT: i32

const ETIMEDOUT: i32

namespace __fs_errno_fn

Functions

function errno_location(): *mut i32

Returns the thread-local errno pointer on Linux.

namespace __fs_io

Functions

function close(fd: i32): i32

POSIX close; closes a file descriptor.

function lseek(fd: i32, offset: i64, whence: i32): i64

POSIX lseek; repositions a file descriptor offset.

function mkdir(pathname: *u8, mode: u32): i32

POSIX mkdir; creates one directory with mode.

function read(fd: i32, buf: *mut void, count: u64): i64

POSIX read; returns bytes read, 0 on EOF, or -1.

function rename(oldpath: *u8, newpath: *u8): i32

POSIX rename; renames a filesystem path.

function rmdir(pathname: *u8): i32

POSIX rmdir; removes an empty directory path.

function unlink(pathname: *u8): i32

POSIX unlink; removes a file path.

function write(fd: i32, buf: *mut void, count: u64): i64

POSIX write; returns bytes written or -1.

Constants

const O_APPEND: i32

const O_CREAT: i32

const O_EXCL: i32

const O_RDONLY: i32

const O_RDWR: i32

const O_TRUNC: i32

const O_WRONLY: i32

const S_IFDIR: u32

const S_IFLNK: u32

const S_IFMT: u32

const S_IFREG: u32

const S_IRGRP: u32

const S_IROTH: u32

const S_IRUSR: u32

const S_IRWXG: u32

const S_IRWXO: u32

const S_IRWXU: u32

const S_IWGRP: u32

const S_IWOTH: u32

const S_IWUSR: u32

const S_IXGRP: u32

const S_IXOTH: u32

const S_IXUSR: u32

const SEEK_CUR: i32

const SEEK_END: i32

const SEEK_SET: i32

namespace __fs_path

Functions

function realpath(pathname: *u8, resolvedPath: *u8): *mut u8

POSIX realpath; resolves an absolute canonical path.

namespace __fs_rt

Functions

function ignis_dirent_ino(entry: *mut void): u64

Returns the inode from a host dirent.

function ignis_dirent_name(entry: *mut void): *u8

Returns the d_name pointer from a host dirent.

function ignis_dirent_type(entry: *mut void): u8

Returns the file-type byte from a host dirent.

function ignis_fstat_call(fd: i32, outDev: &mut u64, outIno: &mut u64, outMode: &mut u32, outNlink: &mut u64, outUid: &mut u32, outGid: &mut u32, outSize: &mut i64, outAtime: &mut i64, outMtime: &mut i64, outCtime: &mut i64, outBlksize: &mut i64, outBlocks: &mut i64): i32

Runtime bridge for fstat(2) with layout-independent out parameters.

function ignis_lstat_call(path: *u8, outDev: &mut u64, outIno: &mut u64, outMode: &mut u32, outNlink: &mut u64, outUid: &mut u32, outGid: &mut u32, outSize: &mut i64, outAtime: &mut i64, outMtime: &mut i64, outCtime: &mut i64, outBlksize: &mut i64, outBlocks: &mut i64): i32

Runtime bridge for lstat(2) that does not follow symlinks.

function ignis_open3(pathname: *u8, flags: i32, mode: u32): i32

Runtime bridge for variadic open(path, flags, mode).

function ignis_readdir_call(dirp: *mut void, outName: &mut u64, outIno: &mut u64, outType: &mut u8): i32

Runtime bridge for readdir with extracted out parameters.

function ignis_remove_dir_all_call(path: *u8): i32

Runtime recursive directory removal helper.

function ignis_stat_call(path: *u8, outDev: &mut u64, outIno: &mut u64, outMode: &mut u32, outNlink: &mut u64, outUid: &mut u32, outGid: &mut u32, outSize: &mut i64, outAtime: &mut i64, outMtime: &mut i64, outCtime: &mut i64, outBlksize: &mut i64, outBlocks: &mut i64): i32

Runtime bridge for stat(2) with layout-independent out parameters.

namespace Sys

POSIX filesystem backend used by supported Unix-like targets.

Records

record Stat

File metadata returned by stat and fstat.

Fields correspond to POSIX struct stat members. Times are seconds since the Unix epoch (tv_sec only; sub-second precision is not exposed).

Members

dev: u64

ino: u64

mode: u32

nlink: u64

uid: u32

gid: u32

size: i64

atime: i64

mtime: i64

ctime: i64

blksize: i64

blocks: i64

record SysDirEntry

Single entry read from a directory stream via readdir.

The name field is borrowed from the internal C dirent buffer — valid only until the next readdir call or closedir.

Members

name: str

File name (borrowed — valid until next readdir/closedir).

ino: u64

Inode number.

fileType: u8

File type hint (DT_REG, DT_DIR, etc.). 0 if unknown.

Functions

function close(fd: i32): Result<void, IoError>

Closes file descriptor fd.

function closedir(dirp: *mut void): void

Closes a directory stream opened with opendir.

function fstat(fd: i32): Result<Stat, IoError>

Returns file metadata for open file descriptor fd.

function lastError(): IoError

Converts current errno into the portable Io::IoError representation.

function lseek(fd: i32, offset: i64, whence: i32): Result<i64, IoError>

Repositions the file offset of fd.

whence is SEEK_SET, SEEK_CUR, or SEEK_END.

function lstat(path: str): Result<Stat, IoError>

Returns file metadata for path without following symlinks.

function mkdir(path: str, mode: u32): Result<void, IoError>

Creates a directory at path with the given permission mode.

function open(path: str, flags: i32, mode: u32): Result<i32, IoError>

Opens path with flags and mode. Returns the fd on success.

Uses the 3-argument open(2) so mode is always available for O_CREAT. Pass 0 for mode when not creating.

function opendir(path: str): Result<*mut void, IoError>

Opens a directory stream for reading entries.

The returned DirPtr must be closed with closedir when done.

function read(fd: i32, buf: *mut void, count: u64): Result<i64, IoError>

Reads up to count bytes from fd into buf.

Returns the number of bytes actually read (0 means EOF).

function readdir(dirp: *mut void): Result<Option<SysDirEntry>, IoError>

Reads the next entry from a directory stream.

Returns Result::OK(Option::NONE) when the end of the directory is reached. The returned SysDirEntry borrows its name from the internal dirent buffer — valid only until the next readdir or closedir.

function readdirEntry(dirp: *mut void, outName: &mut u64, outIno: &mut u64, outType: &mut u8): Result<boolean, IoError>

Reads the next entry from a directory stream.

function realpath(path: str): Result<String, IoError>

Resolves path to an existing canonical absolute path.

function removeDirAll(path: str): Result<void, IoError>

Recursively removes a directory tree without following symlink directories.

function rename(oldPath: str, newPath: str): Result<void, IoError>

Renames oldPath to newPath.

function rmdir(path: str): Result<void, IoError>

Removes the empty directory at path.

function stat(path: str): Result<Stat, IoError>

Returns file metadata for path.

function tempDirCandidate(value: *mut u8): Option<String>

Returns a temp-dir candidate only when the raw path is non-empty and a directory.

function tempDirPath(): Result<String, IoError>

Returns the host temporary-directory root.

function unlink(path: str): Result<void, IoError>

Removes the file at path.

function write(fd: i32, buf: *mut void, count: u64): Result<i64, IoError>

Writes up to count bytes from buf to fd.

Returns the number of bytes actually written.

Constants

const DT_DIR: u8

const DT_LNK: u8

const DT_REG: u8

const DT_UNKNOWN: u8

const O_APPEND: i32

const O_CREAT: i32

const O_EXCL: i32

const O_RDONLY: i32

const O_RDWR: i32

const O_TRUNC: i32

const O_WRONLY: i32

const S_IFDIR: u32

const S_IFLNK: u32

const S_IFMT: u32

const S_IFREG: u32

const S_IRGRP: u32

const S_IROTH: u32

const S_IRUSR: u32

const S_IRWXG: u32

const S_IRWXO: u32

const S_IRWXU: u32

const S_IWGRP: u32

const S_IWOTH: u32

const S_IWUSR: u32

const S_IXGRP: u32

const S_IXOTH: u32

const S_IXUSR: u32

const SEEK_CUR: i32

const SEEK_END: i32

const SEEK_SET: i32