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. 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.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.3. Structures

df_header

struct df_header

4.1.4. Handled structures

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.

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.

4.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.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.6.1. fload

fload(file: file; size: int; blk: block<(data:array<uint8>):void>)

def fload (file: file; size: int; blk: block<(data:array<uint8>):void>)

Arguments:

  • file : file

  • size : int

  • blk : block<(data:array<uint8>):void>

fload(f: file; buf: auto(BufType)): auto
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.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?
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.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; buf: auto(BufType)): auto
fread(f: file; buf: array<auto(BufType)>): auto
fread(f: file; blk: block<(data:string#):auto>): auto
fread(path: string): string
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.6.4. fstat

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

Retrieves file metadata such as size and timestamps into an FStat structure from a file handle, equivalent to C fstat.

Arguments:

  • file : FILE? implicit

  • stat : FStat implicit

fstat(f: file): FStat
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.6.5. fwrite

fwrite(f: file; buf: array<auto(BufType)>): auto

def fwrite (f: file; buf: array<auto(BufType)>) : auto

Arguments:

  • f : file

  • buf : array<auto(BufType)> implicit

fwrite(file: FILE const?; text: string)
fwrite(f: file; buf: auto(BufType)): auto
fwrite(path: string; text: string): bool
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.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.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.6.8. stat

stat(path: string): FStat

def stat (path: string) : FStat

Arguments:

  • path : string

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

4.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

4.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.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.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.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.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.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.9. 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.9.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.10. 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_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.11. Dynamic modules

4.1.11.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