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 (path_join, base_name, dir_name), and file metadata queries (stat, file_size).

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.

  • tilde_home(text) : string — every home directory in text (/Users/<name>/, /home/<name>/, <drive>:\Users\<name>\ or <drive>:/Users/<name>/) rewritten as ~/ (~\ on the backslash drive form) wherever it starts a path: the path under the home survives, the user name does not; a bare home with no separator after the name stays.

  • 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

process = SubProcess?

typedef process = fio_core::SubProcess? aka process

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.

process_running = -2147483648

The value process_poll and process_wait return while the child is still running. INT32_MIN: no signal number and no ordinary exit code takes that value; the one collision is a Windows process that returns 0x80000000 as its own status on purpose.

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.

FStat.is_exec(): bool

Returns true if the file status carries an execute permission - any of the owner, group or other execute bits on POSIX; on Windows, an executable extension (.exe, .cmd, .bat, .com). A directory reports true on both, so a test for a program pairs it with is_reg.

Properties:

  • size : uint64

    • atime : clock

    • ctime : clock

    • mtime : clock

    • is_reg : bool

    • is_dir : bool

    • is_exec : bool

stat and fstat return file information in this structure.

Fields:

  • is_valid : bool - True if the file information was retrieved successfully.

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.

SubProcess

A long-lived child process spawned by spawn_process: an opaque handle a supervisor polls, drains and signals across many ticks, unlike the block-scoped popen_argv. Free it with close_process, or hold it in a with_process block.

4.1.1.6. Direct IO and mapping advice

dwrite_append(writer: void?; data: void?; bytes: uint64 ): bool

Warning

This is unsafe operation.

Append bytes from data at the writer’s current end. Any pointer, any size — the handle re-blocks into aligned bands internally, and a band-multiple, band-aligned source is written directly with no copy. Returns false when a write fails (disk full, in practice); a failed writer stays failed, so checking dwrite_close once is enough.

Arguments:

  • writer : void? implicit

  • data : void? implicit

  • bytes : uint64

dwrite_band(writer: void?; avail: uint64? ): void?

Warning

This is unsafe operation.

Hand out the writer’s own staging band so a producer can build bytes in place instead of building a buffer and appending a copy. avail receives the free space left in the current band; fill up to that many bytes and account for them with dwrite_commit. Returns null on a dead writer.

Arguments:

  • writer : void? implicit

  • avail : uint64? implicit

dwrite_close(writer: void? ): bool

Warning

This is unsafe operation.

Flush the writer’s tail (sector-padded on cache-bypassing platforms), truncate the file to exactly what was appended, and free the handle. Returns false if anything failed anywhere along the writer’s life — this is the one completion verdict a caller needs to check.

Arguments:

  • writer : void? implicit

dwrite_commit(writer: void?; bytes: uint64 ): bool

Warning

This is unsafe operation.

Account bytes written into the pointer dwrite_band handed out; a full band flushes to the device automatically. Returns false when the commit overruns the band’s remaining space (a producer bug) or the writer already failed.

Arguments:

  • writer : void? implicit

  • bytes : uint64

dwrite_open(path: string; total_bytes: uint64; band_bytes: uint64 ): void?

Warning

This is unsafe operation.

Open path for cache-bypassing sequential append (FILE_FLAG_NO_BUFFERING on Windows, F_NOCACHE on macOS, posix_fallocate plus fadvise elsewhere). total_bytes preallocates the file — writes must then be strictly ascending, which is what avoids NTFS valid-data-length zero-fill; the file is truncated back to what was actually appended at close. band_bytes sizes the internal sector-aligned bounce buffer (16 MB when in doubt). Returns null on failure. Pair with dwrite_append or the dwrite_band/dwrite_commit producer surface, and always finish with dwrite_close.

Arguments:

  • path : string implicit

  • total_bytes : uint64

  • band_bytes : uint64

dwrite_stat(writer: void?; which: int ): uint64

Warning

This is unsafe operation.

Where the writer spent its time so far: which 0 = staging nanoseconds (memcpy into the bounce band), 1 = syscall nanoseconds, 2 = bytes written directly from caller memory, 3 = bytes that went through the bounce band. Call before dwrite_close — the handle is gone after.

Arguments:

  • writer : void? implicit

  • which : int

prefetch_map(base: void?; bytes: uint64 ): bool

Warning

This is unsafe operation.

Advisory readahead over a mapped range: asks the OS to fault bytes starting at base into the page cache ahead of use (PrefetchVirtualMemory on Windows, madvise(MADV_WILLNEED) on POSIX). Use it on an fmap/fmap_open mapping before a parallel pass over the data — on-demand faults taken inside worker lanes serialize them. Returns false when the OS declines; the call is purely advisory, so reads work either way.

Arguments:

  • base : void? implicit

  • bytes : uint64

4.1.1.7. 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.7.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: int64; 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

fmap_close(data: void?; size: uint64 )

Warning

This is unsafe operation.

Unmaps a mapping produced by fmap_open. data and size must be exactly the base pointer and byte count that fmap_open returned; every pointer or borrowed view into the mapping is invalid after the call.

Arguments:

  • data : void? implicit

  • size : uint64

fmap_open(path: string; size: uint64? ): void?

Warning

This is unsafe operation.

Memory-maps the file at path read-only and returns the mapping’s base pointer, writing the mapped byte count through size. Unlike fmap the mapping is not scope-bound: it stays valid until passed to fmap_close, so long-lived borrowed views (e.g. dasLLAMA’s prepared-model images) can be built over it. Returns null when the file cannot be opened or mapped.

Arguments:

  • path : string implicit

  • size : uint64? implicit

fmap_open_rw(path: string; size: uint64? ): void?

Warning

This is unsafe operation.

The writable twin of fmap_open: memory-maps the file at path as a SHARED read-write view and returns the mapping’s base pointer, writing the mapped byte count through size. Writes through the mapping go back to the file itself via the page cache — this is a real shared mapping, not copy-on-write, so no commit charge is taken for the view. The mapping stays valid until passed to fmap_close. Returns null when the file cannot be opened for writing, is empty, or cannot be mapped.

Arguments:

  • path : string implicit

  • size : uint64? implicit

4.1.1.7.2. fopen

fopen(name: string; mode: string ): FILE const?

Opens the file at name with the given mode (e.g. "r", "w", "rb", "a+") and returns a file handle, or null if the file cannot be opened. Throws if name is null or if mode is not a valid fopen mode string (first char must be r/w/a; remaining chars limited to +/b/t/x).

Arguments:

  • name : string implicit

  • mode : string implicit

fopen(name: string; mode: string; blk: block<(f:file):void> ): auto
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.7.3. fread

fread(f: file; blk: block<(data:string#):auto> ): auto

def fread (f: file; blk: block<(data:string#):auto>) : auto

Arguments:
fread(f: file; buf: array<auto(BufType)> ): auto
fread(f: file; buf: auto(BufType) ): auto
fread(file: FILE const? ): string
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.1.7.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.7.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(f: file; buf: auto(BufType) ): auto
fwrite(file: FILE const?; text: string )
fwrite(path: string; text: string ): bool
getchar(): int

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

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

Returns true if the path is a symbolic link — and on Windows, any reparse point: a junction, a mount point, or a less common flavor such as a cloud-file placeholder. Reports errors via the error out-parameter.

Arguments:

  • path : string implicit

  • error : string& implicit

is_reparse_point_result(path: string ): fs_result_bool

def is_reparse_point_result (path: string) : fs_result_bool

Arguments:

  • path : string

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

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

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

Arguments:

  • f : file

  • buf : array<auto(BufType)> implicit

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

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

Arguments:

  • f : file

  • buf : array<auto(BufType)> implicit

4.1.1.7.6. remove

remove(name: string ): bool

Deletes the file at the specified path and returns true if it was removed successfully.

Arguments:

  • name : string implicit

remove(name: string; error: string& ): bool
remove_result(path: string ): fs_result_bool

def remove_result (path: string) : fs_result_bool

Arguments:

  • path : string

4.1.1.7.7. rename

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

Renames or moves a file from old_name to new_name and returns true on success.

Arguments:

  • old_name : string implicit

  • new_name : string implicit

rename(old_name: string; new_name: string; error: 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: clock ): fs_result_bool

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

Arguments:

  • path : string

  • time : clock

4.1.1.7.8. stat

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

Returns the file status (size, modification time, etc.) for a file at the given path.

Arguments:

  • file : string implicit

  • stat : FStat implicit

stat(path: string ): FStat

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

tilde_home(text: string ): string

def tilde_home (text: string) : string

Arguments:

  • text : string

to_generic_path(s: string ): string

def to_generic_path (s: string) : string

Arguments:

  • s : string

4.1.1.9. 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.9.1. dir_rec

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

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

Arguments:

  • path : string

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

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

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

4.1.1.9.2. mkdir

mkdir(path: string ): bool

Creates a single directory at the specified path and returns true if it was created successfully.

Arguments:

  • path : string implicit

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

4.1.1.9.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.9.4. rmdir

rmdir(path: string ): bool

Removes an empty directory. Returns true on success.

Arguments:

  • path : string implicit

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

4.1.1.9.5. rmdir_rec

rmdir_rec(path: string ): bool

Recursively removes a directory and all its contents (files and subdirectories). Returns true on success.

Arguments:

  • path : string implicit

rmdir_rec(path: string; error: 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.10. 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.11. 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.11.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.12. Terminal queries

is_terminal(fd: int ): bool

Returns true when the standard stream fd (0 for input, 1 for output, 2 for error) is attached to a terminal. Any other descriptor, and every stream that is a pipe or a file, returns false.

Arguments:

  • fd : int

terminal_width(): int

Returns the terminal width in columns, or 0 when nothing reports one — the stream is not a terminal, or the platform query failed. Falls back to the COLUMNS environment variable before giving up.

4.1.1.13. OS specific routines

close_process(process: SubProcess? )

Warning

This is unsafe operation.

Frees the handle. A child still running dies with it - the Windows job object closes, the POSIX process group is killed and reaped - so a supervisor never leaks a child or leaves a zombie. A null handle is ignored.

Arguments:
exit(exitCode: int )

Warning

This is unsafe operation.

Terminates the program immediately with the specified integer exit code, equivalent to C exit. A non-zero code is reported with the calling script location and a daslang stack trace, so the exit is not silent; exit(0) is a normal shutdown and prints nothing.

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_argv_pipe(args: array<anything>; scope: block<(FILE const?;FILE const?):void> ): int

Warning

This is unsafe operation.

Spawns a subprocess with bidirectional pipes connected to its stdin and stdout (child stderr is merged into stdout). The block receives two FILE *: a writable stdin handle (parent → child) and a readable stdout handle (child → parent). When the block returns, the parent closes stdin (signalling EOF to the child), waits for the child to exit, closes stdout, and returns the child’s exit code. Argv-based: bypasses the shell entirely (Windows CreateProcess; Unix fork + execvp) — no quote-stripping, no $(…) / backtick expansion. args[0] is the executable, remaining elements are positional arguments. Returns -1 if the process could not be spawned or pipes could not be created.

Arguments:

  • args : array implicit

  • scope : block<( FILE?; 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

process_alive(pid: int ): bool

Warning

This is unsafe operation.

Whether a process with this id exists - any process, not only a child - for a single-instance guard reading a pid file. Probes without signalling: kill(pid, 0) on POSIX (a process that exists but is not ours to signal counts as alive), OpenProcess plus the still-active exit status on Windows. A pid of zero or less is never alive.

Arguments:

  • pid : int

process_drain(process: SubProcess?; block: block<(string):void> ): bool

Warning

This is unsafe operation.

Hands block every complete line of the child’s merged stdout+stderr that is ready right now, one call per line with the newline stripped, and never blocks: a partial line waits in the handle for the next drain, and a last line with no newline is delivered once the child closes its output. Returns false once that output is closed and fully delivered, so a supervisor drains on every tick until it does.

Arguments:

  • process : SubProcess? implicit

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

process_kill(process: SubProcess? )

Warning

This is unsafe operation.

Kills the child and everything it spawned: SIGKILL to its process group on POSIX, TerminateJobObject with exit code 9 on Windows. Nothing in the child runs after this.

Arguments:
process_pid(process: SubProcess? ): int

Warning

This is unsafe operation.

The child’s process id, for a pid file or a log line.

Arguments:
process_poll(process: SubProcess? ): int

Warning

This is unsafe operation.

The child’s exit code if it has exited, else process_running; never waits. On POSIX a child killed by a signal reports the signal number, as popen_argv does. The code is remembered, so a later call answers the same.

Arguments:
process_terminate(process: SubProcess? )

Warning

This is unsafe operation.

Asks the child and everything it spawned to stop: SIGTERM to its process group on POSIX, TerminateJobObject with exit code 15 on Windows, where nothing gentler reaches a console-less process. Follow with process_wait and, if still running, process_kill.

Arguments:
process_wait(process: SubProcess?; timeout: float ): int

Warning

This is unsafe operation.

Waits up to timeout seconds for the child to exit and returns its exit code, or process_running when the timeout passes first. A timeout of zero or less waits forever. The code is remembered, so a later process_poll answers the same.

Arguments:
run_and_capture(args: array<string>; output: string&; timeout_sec: float = 0f ): int

def run_and_capture (args: array<string>; var output: string&; timeout_sec: float = 0f) : int

Arguments:

  • args : array<string>

  • output : string&

  • timeout_sec : float

sanitize_command_line(var: string ): string

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

Arguments:

  • var : string implicit

set_env_variable(var: string; value: string )

Sets an environment variable in the current process (the setenv/_putenv family). The change is visible to subsequent get_env_variable calls and inherited by child processes spawned afterwards (popen, spawn_argv); it does not affect the parent shell.

Arguments:

  • var : string implicit

  • value : string implicit

sleep(msec: uint )

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

Arguments:

  • msec : uint

spawn_argv(args: array<anything> ): bool

Warning

This is unsafe operation.

Launches a detached subprocess directly from an argument array without invoking a shell. args[0] is the executable and the remaining elements are passed as individual arguments, so spaces and shell metacharacters are preserved literally. The child inherits the current working directory, environment, and standard output/error; standard input is disconnected.

Returns true once the executable has been started and does not wait for it to exit. Returns false if the process could not be created or the executable could not be started.

Arguments:

  • args : array implicit

spawn_process(argv: array<anything>; cwd: string; env: array<anything> ): SubProcess?

Warning

This is unsafe operation.

Spawns argv as a long-lived child and returns its handle. No shell is involved: argv[0] is the executable (a forward-slash path spawns on every platform; a relative path naming a directory resolves against the caller’s directory, not cwd), the rest are its arguments verbatim. cwd empty inherits the caller’s directory; each env entry is a KEY=VALUE override applied over the inherited environment. The child’s stdout and stderr merge into one pipe read by process_drain; its stdin is empty. On Windows the child sits in a kill-on-close job object, on POSIX it leads its own process group, so process_terminate / process_kill reach the whole tree and closing the handle kills a child still running. An unspawnable executable is a thrown error on Windows and an exit code 127 on POSIX.

Arguments:

  • argv : array implicit

  • cwd : string implicit

  • env : array implicit

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.13.1. with_process

with_process(argv: array<string>; blk: block<(var p:process):void> )

def with_process (argv: array<string>; blk: block<(var p:process):void>)

Arguments:

  • argv : array<string>

  • blk : block<(p: process):void>

with_process(argv: array<string>; cwd: string; env: array<string>; blk: block<(var p:process):void> )

4.1.1.14. Dynamic modules

describe_pending_dynamic_modules(): string

One line per dynamic module whose shared library failed to load during the module scan, with the loader error; empty when nothing is pending. Lets a library report why an optional native module is absent instead of silently dropping the capability.

no_manifest()

Called from a .das_module descriptor’s initialize: marks the descriptor as one that runs on every start, so the module scan keeps no manifest of its registrations and never replays them. Use it when what the descriptor registers depends on something its file content cannot see.

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