4.1. File input output library

The FIO module implements file input/output and filesystem operations. It provides functions for reading and writing files (fopen, fread, fwrite), directory management (mkdir, dir), path manipulation (join_path, basename, dirname), and file metadata queries (stat, file_time).

All functions and symbols are in “fio” module, use require to get access to it.

require daslib/fio

Example:

require daslib/fio

    [export]
    def main() {
        let fname = "_test_fio_tmp.txt"
        fopen(fname, "wb") $(f) {
            fwrite(f, "hello, daslang!")
        }
        fopen(fname, "rb") $(f) {
            let content = fread(f)
            print("{content}\n")
        }
        remove(fname)
    }
    // output:
    // hello, daslang!

4.1.1. Glob and pattern matching

The fio module also provides path-aware glob matching and expansion. match_glob, glob, glob_filtered, is_glob_pattern and to_generic_path are the low-level primitives; expand_glob and parse_file_list are the higher-level helpers used by CLI tools that take a user-supplied pattern or a comma/newline-separated list of paths.

  • match_glob(pattern, path) : bool — pure path-string match. * does not cross /; ** does. [abc] / [a-z] / [!abc] / [^abc] character classes are supported.

  • glob(root, pattern, blk) — recursive walk + match in one pass. Callback receives /-normalized paths regardless of host OS.

  • glob_filtered(root, includes, excludes, blk) — multi-pattern walk; excludes win on conflict.

  • is_glob_pattern(pattern) : bool — true if the string contains *, ?, or [.

  • to_generic_path(s) : string — convert a path to use forward slashes regardless of host.

  • expand_glob(pattern, var result) — expand a single glob pattern (e.g. src/**/*.das) into a sorted list of matching file paths. Splits the literal directory prefix from the glob remainder, picks recursive vs shallow walk based on whether the remainder contains ** or /, filters out directories, sorts locally, and appends to result.

  • parse_file_list(file, var result) — parse a comma- or newline-separated list of files, directories, and globs into a flat list of paths. Strips whitespace, skips empty entries, literal entries pass through, glob entries go through expand_glob. Also appends to result.

require daslib/fio

[export]
def main() {
    // expand a single pattern
    var das_files : array<string>
    expand_glob("daslib/**/*.das", das_files)
    for (f in das_files) { print("{f}\n") }

    // parse a user-supplied paths argument: any mix of plain paths and globs
    var inputs : array<string>
    parse_file_list("README.md,daslib/*.das,tests/fio/*.das", inputs)
}

For runnable examples covering every flavor, see tutorials/language/54_glob.das.

4.1.1.1. Type aliases

file = FILE const?

typedef file = fio_core::FILE const? aka file

variant fs_result_bool

variant<value:bool;error:string> aka fs_result_bool

variant fs_result_int64

variant<value:int64;error:string> aka fs_result_int64

variant fs_result_string

variant<value:string;error:string> aka fs_result_string

4.1.1.2. Constants

seek_set = 0

Constant for fseek that positions the file pointer relative to the beginning of the file by the given offset.

seek_cur = 1

Constant for fseek that positions the file pointer relative to its current position by the given offset.

seek_end = 2

Constant for fseek that positions the file pointer relative to the end of the file by the given offset.

popen_timed_out = 2147483393

Sentinel exit code returned by popen_timeout when the process was killed due to exceeding the timeout.

df_magic = 0x12345678

df_magic:uint const

4.1.1.3. Structures

df_header

struct df_header

4.1.1.4. Handled structures

FStat
FStat.size(): uint64

Returns the size of the file in bytes.

FStat.atime(): clock

Returns the last access time of the file as a clock value.

FStat.ctime(): clock

Returns the creation time of the file as a clock value.

FStat.mtime(): clock

Returns the last modification time of the file as a clock value.

FStat.is_reg(): bool

Returns true if the file status indicates a regular file.

FStat.is_dir(): bool

Returns true if the file status indicates a directory.

Properties:

  • size : uint64

  • atime : clock

  • ctime : clock

  • mtime : clock

  • is_reg : bool

  • is_dir : bool

Fields:

  • is_valid : bool - stat and fstat return file information in this structure.

DiskSpaceInfo

Disk space information for a filesystem.

Fields:

  • capacity : uint64 - Total storage capacity in bytes.

  • free : uint64 - Amount of free space in bytes.

  • available : uint64 - Amount of space available to non-privileged users in bytes.

4.1.1.5. Handled types

FILE

Opaque handle wrapping the platform-specific C FILE type used by all low-level file I/O functions.

4.1.1.6. File manipulation

copy_file(src: string; dst: string; overwrite: bool; error: string&): bool

Copies a file from src to dst. Reports errors via the error out-parameter. If overwrite is false, fails when dst already exists.

Arguments:

  • src : string implicit

  • dst : string implicit

  • overwrite : bool

  • error : string& implicit

copy_file_result(src: string; dst: string; overwrite: bool): fs_result_bool

def copy_file_result (src: string; dst: string; overwrite: bool) : fs_result_bool

Arguments:

  • src : string

  • dst : string

  • overwrite : bool

equivalent(a: string; b: string; error: string&): bool

Returns true if two paths refer to the same file or directory. Reports errors via the error out-parameter.

Arguments:

  • a : string implicit

  • b : string implicit

  • error : string& implicit

equivalent_result(a: string; b: string): fs_result_bool

def equivalent_result (a: string; b: string) : fs_result_bool

Arguments:

  • a : string

  • b : string

fclose(file: FILE const?)

Closes the given FILE pointer and releases its associated resources, equivalent to C fclose.

Arguments:

  • file : FILE? implicit

feof(file: FILE const?): bool

Returns true if the end-of-file indicator has been set on the given FILE pointer, equivalent to C feof.

Arguments:

  • file : FILE? implicit

fexist(path: string): bool

Returns true if a file or directory exists at the given path.

Arguments:

  • path : string implicit

fflush(file: FILE const?)

Flushes any buffered output data for the given FILE pointer to the underlying file, equivalent to C fflush.

Arguments:

  • file : FILE? implicit

fgets(file: FILE const?): string

Reads and returns the next line as a string from the given FILE pointer, equivalent to C fgets.

Arguments:

  • file : FILE? implicit

file_size(path: string; error: string&): int64

Returns the size of a file in bytes. Reports errors via the error out-parameter.

Arguments:

  • path : string implicit

  • error : string& implicit

file_size_result(path: string): fs_result_int64

def file_size_result (path: string) : fs_result_int64

Arguments:

  • path : string

4.1.1.6.1. fload

fload(f: file; buf: auto(BufType)): auto

def fload (f: file; var buf: auto(BufType)) : auto

Arguments:

  • f : file

  • buf : auto(BufType)

fload(file: file; size: int; blk: block<(data:array<uint8>):void>)
fmap(file: FILE const?; block: block<(array<uint8>#):void>)

Memory-maps the contents of the given FILE pointer and provides the data as an array of uint8 inside the block.

Arguments:

  • file : FILE? implicit

  • block : block<(array<uint8>#):void> implicit

4.1.1.6.2. fopen

fopen(name: string; mode: string; blk: block<(f:file):void>): auto

def fopen (name: string; mode: string; blk: block<(f:file):void>) : auto

Arguments:

  • name : string

  • mode : string

  • blk : block<(f: file):void>

fopen(name: string; mode: string): FILE const?
for_each_registered_dynamic_module(block: block<(string;string;string):void>)

Iterates over all registered dynamic modules, invoking the block with the library path, C++ module name, and daslang module name for each entry.

Arguments:

  • block : block<(string;string;string):void> implicit

for_each_registered_native_path(block: block<(string;string;string):void>)

Iterates over all registered native path mappings, invoking the block with the module name, source prefix, and destination prefix for each entry.

Arguments:

  • block : block<(string;string;string):void> implicit

fprint(file: FILE const?; text: string)

Writes the given text string to the specified FILE pointer, equivalent to print but targeting a file.

Arguments:

  • file : FILE? implicit

  • text : string implicit

4.1.1.6.3. fread

fread(file: FILE const?): string

Reads the entire contents of an open file and returns it as a string.

Arguments:

  • file : FILE? implicit

fread(f: file; blk: block<(data:string#):auto>): auto
fread(f: file; buf: auto(BufType)): auto
fread(f: file; buf: array<auto(BufType)>): auto
fread(path: string): string
fread_to_eof(f: FILE const?): string

Warning

This is unsafe operation.

Drains an open file/pipe/socket to EOF using a 64 KB growing buffer and returns the captured bytes as a string. Use this for streams without a known size (pipes, subprocess output, sockets, stdin) where fread returns an empty string because fstat().st_size reports 0.

Arguments:

  • f : FILE? implicit

fsave(f: file; buf: auto(BufType)): auto

def fsave (f: file; buf: auto(BufType)) : auto

Arguments:

  • f : file

  • buf : auto(BufType)

fseek(file: FILE const?; offset: int64; mode: int): int64

Repositions the file pointer of the given FILE to the specified offset relative to the mode (seek_set, seek_cur, or seek_end) and returns the new position.

Arguments:

  • file : FILE? implicit

  • offset : int64

  • mode : int

4.1.1.6.4. fstat

fstat(f: file): FStat

def fstat (f: file) : FStat

Arguments:
fstat(file: FILE const?; stat: FStat): bool
fstderr(): FILE const?

Returns the FILE pointer corresponding to the standard error stream.

fstdin(): FILE const?

Returns the FILE pointer corresponding to the standard input stream.

fstdout(): FILE const?

Returns the FILE pointer corresponding to the standard output stream.

ftell(file: FILE const?): int64

Returns the current byte offset of the file pointer for the given FILE, equivalent to C ftell.

Arguments:

  • file : FILE? implicit

4.1.1.6.5. fwrite

fwrite(file: FILE const?; text: string)

Writes a string, typed buffer, or array of data to the specified file handle.

Arguments:

  • file : FILE? implicit

  • text : string implicit

fwrite(f: file; buf: array<auto(BufType)>): auto
fwrite(path: string; text: string): bool
fwrite(f: file; buf: auto(BufType)): auto
getchar(): int

Reads and returns the next character from standard input as an integer, equivalent to C getchar.

Returns true if the path is a symbolic link. Reports errors via the error out-parameter.

Arguments:

  • path : string implicit

  • error : string& implicit

def is_symlink_result (path: string) : fs_result_bool

Arguments:

  • path : string

4.1.1.6.6. remove

remove(name: string; error: string&): bool

Removes a file at the specified path. Reports errors via the error out-parameter.

Arguments:

  • name : string implicit

  • error : string& implicit

remove(name: string): bool
remove_result(path: string): fs_result_bool

def remove_result (path: string) : fs_result_bool

Arguments:

  • path : string

4.1.1.6.7. rename

rename(old_name: string; new_name: string; error: string&): bool

Renames or moves a file or directory from src to dst. Reports errors via the error out-parameter.

Arguments:

  • old_name : string implicit

  • new_name : string implicit

  • error : string& implicit

rename(old_name: string; new_name: string): bool
rename_result(old_name: string; new_name: string): fs_result_bool

def rename_result (old_name: string; new_name: string) : fs_result_bool

Arguments:

  • old_name : string

  • new_name : string

set_mtime(path: string; time: clock; error: string&): bool

Sets the last modification time of a file or directory. Reports errors via the error out-parameter.

Arguments:

  • path : string implicit

  • time : clock

  • error : string& implicit

set_mtime_result(path: string; time: Time): fs_result_bool

def set_mtime_result (path: string; time: Time) : fs_result_bool

Arguments:

  • path : string

  • time : Time

4.1.1.6.8. stat

stat(path: string): FStat

def stat (path: string) : FStat

Arguments:

  • path : string

stat(file: string; stat: FStat): bool

4.1.1.7. Path manipulation

base_name(name: string): string

Extracts and returns the final component of a file path, equivalent to POSIX basename.

Arguments:

  • name : string implicit

dir_name(name: string): string

Extracts and returns the directory component of a file path, equivalent to POSIX dirname.

Arguments:

  • name : string implicit

extension(path: string): string

Returns the file extension including the dot (e.g. “.txt”), or empty string if no extension.

Arguments:

  • path : string implicit

get_full_file_name(path: string): string

Returns the fully resolved and normalized absolute path for the given file path string.

Arguments:

  • path : string implicit

is_absolute(path: string): bool

Returns true if the path is an absolute path (rooted).

Arguments:

  • path : string implicit

normalize(path: string): string

Returns the lexically normalized path with redundant separators, “.” and “..” resolved.

Arguments:

  • path : string implicit

parent(path: string): string

Returns the parent directory of the path, or empty string if at root level.

Arguments:

  • path : string implicit

path_join(a: string; b: string): string

Joins two path components with the platform-native separator.

Arguments:

  • a : string implicit

  • b : string implicit

relative(path: string; base: string; error: string&): string

Returns a relative path from base to path. Reports errors via the error out-parameter.

Arguments:

  • path : string implicit

  • base : string implicit

  • error : string& implicit

relative_result(path: string; base: string): fs_result_string

def relative_result (path: string; base: string) : fs_result_string

Arguments:

  • path : string

  • base : string

replace_extension(path: string; new_ext: string): string

Returns a new path with the file extension replaced by new_ext (include the dot, e.g. “.md”).

Arguments:

  • path : string implicit

  • new_ext : string implicit

stem(path: string): string

Returns the filename without its extension (e.g. “file” from “file.txt”).

Arguments:

  • path : string implicit

to_generic_path(s: string): string

def to_generic_path (s: string) : string

Arguments:

  • s : string

4.1.1.8. Directory manipulation

chdir(path: string): bool

Changes the current working directory to the specified path and returns true on success.

Arguments:

  • path : string implicit

dir(path: string; blk: block<(filename:string):void>): auto

def dir (path: string; blk: block<(filename:string):void>) : auto

Arguments:

  • path : string

  • blk : block<(filename:string):void>

4.1.1.8.1. dir_rec

dir_rec(path: string; blk: block<(filename:string;is_dir:bool):void>; error: string&): auto

def dir_rec (path: string; blk: block<(filename:string;is_dir:bool):void>; var error: string&) : auto

Arguments:

  • path : string

  • blk : block<(filename:string;is_dir:bool):void>

  • error : string&

dir_rec(path: string; blk: block<(filename:string;is_dir:bool):void>): auto
getcwd(): string

Returns the absolute path of the current working directory as a string.

4.1.1.8.2. mkdir

mkdir(path: string; error: string&): bool

Creates a single directory at the specified path. Reports errors via the error out-parameter.

Arguments:

  • path : string implicit

  • error : string& implicit

mkdir(path: string): bool

4.1.1.8.3. mkdir_rec

mkdir_rec(path: string): bool

def mkdir_rec (path: string) : bool

Arguments:

  • path : string

mkdir_rec(path: string; error: string&): bool
mkdir_result(path: string): fs_result_bool

def mkdir_result (path: string) : fs_result_bool

Arguments:

  • path : string

4.1.1.8.4. rmdir

rmdir(path: string; error: string&): bool

Removes an empty directory at the specified path. Reports errors via the error out-parameter.

Arguments:

  • path : string implicit

  • error : string& implicit

rmdir(path: string): bool

4.1.1.8.5. rmdir_rec

rmdir_rec(path: string; error: string&): bool

Recursively removes a directory and all its contents. Reports errors via the error out-parameter.

Arguments:

  • path : string implicit

  • error : string& implicit

rmdir_rec(path: string): bool
rmdir_rec_result(path: string): fs_result_bool

def rmdir_rec_result (path: string) : fs_result_bool

Arguments:

  • path : string

rmdir_result(path: string): fs_result_bool

def rmdir_result (path: string) : fs_result_bool

Arguments:

  • path : string

4.1.1.9. Glob and pattern matching

expand_glob(pattern: string; result: array<string>)

def expand_glob (pattern: string; var result: array<string>)

Arguments:

  • pattern : string

  • result : array<string>

glob(root: string; pattern: string; blk: block<(filename:string;is_dir:bool):void>): auto

def glob (root: string; pattern: string; blk: block<(filename:string;is_dir:bool):void>) : auto

Arguments:

  • root : string

  • pattern : string

  • blk : block<(filename:string;is_dir:bool):void>

glob_filtered(root: string; includes: array<string>; excludes: array<string>; blk: block<(filename:string;is_dir:bool):void>): auto

def glob_filtered (root: string; includes: array<string>; excludes: array<string>; blk: block<(filename:string;is_dir:bool):void>) : auto

Arguments:

  • root : string

  • includes : array<string>

  • excludes : array<string>

  • blk : block<(filename:string;is_dir:bool):void>

is_glob_pattern(pattern: string): bool

def is_glob_pattern (pattern: string) : bool

Arguments:

  • pattern : string

match_glob(pattern: string; path: string): bool

def match_glob (pattern: string; path: string) : bool

Arguments:

  • pattern : string

  • path : string

parse_file_list(file: string; result: array<string>)

def parse_file_list (file: string; var result: array<string>)

Arguments:

  • file : string

  • result : array<string>

4.1.1.10. Filesystem queries

create_temp_directory(prefix: string; error: string&): string

Creates a uniquely-named temporary directory with the given prefix. Reports errors via the error out-parameter.

Arguments:

  • prefix : string implicit

  • error : string& implicit

create_temp_directory_result(prefix: string): fs_result_string

def create_temp_directory_result (prefix: string) : fs_result_string

Arguments:

  • prefix : string

create_temp_file(prefix: string; ext: string; error: string&): string

Creates a uniquely-named temporary file with the given prefix. Reports errors via the error out-parameter.

Arguments:

  • prefix : string implicit

  • ext : string implicit

  • error : string& implicit

create_temp_file_result(prefix: string; ext: string): fs_result_string

def create_temp_file_result (prefix: string; ext: string) : fs_result_string

Arguments:

  • prefix : string

  • ext : string

4.1.1.10.1. disk_space

disk_space(path: string): DiskSpaceInfo

def disk_space (path: string) : DiskSpaceInfo

Arguments:

  • path : string

disk_space(path: string; error: string&): DiskSpaceInfo
temp_directory(error: string&): string

Returns the path to the system temporary directory. Reports errors via the error out-parameter.

Arguments:

  • error : string& implicit

temp_directory_result(): fs_result_string

def temp_directory_result () : fs_result_string

4.1.1.11. OS specific routines

exit(exitCode: int)

Warning

This is unsafe operation.

Terminates the program immediately with the specified integer exit code, equivalent to C exit.

Arguments:

  • exitCode : int

get_env_variable(var: string): string

Returns the string value of the environment variable with the given name, or an empty string if undefined.

Arguments:

  • var : string implicit

has_env_variable(var: string): bool

Returns true if an environment variable with the given name is defined in the current process environment.

Arguments:

  • var : string implicit

popen(command: string; scope: block<(FILE const?):void>): int

Warning

This is unsafe operation.

Opens a pipe to the given shell command, provides the resulting FILE pointer to the block, and returns the process exit code.

Arguments:

  • command : string implicit

  • scope : block<( FILE?):void> implicit

popen_argv(args: array<anything>; timeout: float; scope: block<(FILE const?):void>): int

Warning

This is unsafe operation.

Spawns a subprocess directly via argv (Windows: CreateProcess; Unix: fork+execvp), bypassing the shell entirely so arguments are not subject to $(), backtick, or cmd.exe quote-stripping. args[0] is the executable, remaining elements are positional arguments. Provides the captured stdout+stderr FILE pointer to the block and returns the process exit code; if timeout is positive and exceeded, the entire process tree is killed and popen_timed_out is returned.

Arguments:

  • args : array implicit

  • timeout : float

  • scope : block<( FILE?):void> implicit

popen_binary(command: string; scope: block<(FILE const?):void>): int

Warning

This is unsafe operation.

Opens a pipe to the given shell command in binary mode, provides the resulting FILE pointer to the block, and returns the process exit code.

Arguments:

  • command : string implicit

  • scope : block<( FILE?):void> implicit

popen_timeout(command: string; timeout: float; scope: block<(FILE const?):void>): int

Warning

This is unsafe operation.

Opens a process for reading, kills the entire process tree if it exceeds timeout seconds. Returns exit code on normal completion, or popen_timed_out if the timeout was exceeded. If timeout is 0 or negative, behaves identically to popen.

Arguments:

  • command : string implicit

  • timeout : float

  • scope : block<( FILE?):void> implicit

sanitize_command_line(var: string): string

Escapes and sanitizes a command-line argument string to prevent shell injection.

Arguments:

  • var : string implicit

sleep(msec: uint)

Suspends execution of the current thread for the specified number of milliseconds.

Arguments:

  • msec : uint

system(command: string): int

Warning

This is unsafe operation.

Runs a shell command via the C runtime system() function. Returns the process exit code. Unlike popen, this does not capture output — it is fire-and-forget, suitable for launching detached processes (e.g. start on Windows, & on Unix).

Arguments:

  • command : string implicit

4.1.1.12. Dynamic modules

4.1.1.12.1. register_dynamic_module

register_dynamic_module(path: string; name: string): void?

Loads a shared library from the given path and registers it as a daslang module under the specified name, making it available for require.

Arguments:

  • path : string implicit

  • name : string implicit

register_dynamic_module(path: string; name: string; on_error: int): void?
register_native_path(mod_name: string; src: string; dst: string)

Registers a path prefix mapping for a module, redirecting file resolution from the src prefix to the dst prefix.

Arguments:

  • mod_name : string implicit

  • src : string implicit

  • dst : string implicit