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 fio

Example:

require 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

fio::file = FILE const?

Type alias for FILE const? used as the standard file handle parameter type across fio functions.

4.1.2. Constants

fio::seek_set = 0

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

fio::seek_cur = 1

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

fio::seek_end = 2

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

fio::df_magic = 0x12345678

Magic number constant used to identify daslang binary file format. df_magic:uint const

4.1.3. Structures

fio::df_header

Obsolete header structure used by fsave and fload for binary serialization with type identification.

Fields

  • magic : uint - Magic number constant used to identify and validate the file type.

  • size : int - Total size in bytes of the serialized data following this header.

4.1.4. Handled structures

fio::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

fio::FILE

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

4.1.6. File manipulation

fio::fclose(file: FILE const?)

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

Arguments

  • file : FILE? implicit

fio::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

fio::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

fio::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

4.1.6.1. fload

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

Obsolete; loads binary data from a file into the provided buffer or passes it as an array of uint8 to a block.

Arguments

  • file : file

  • size : int

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

fio::fload(f: file; buf: auto(BufType)) : auto()
fio::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

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

Opens the file at the given path with the specified mode string, returning a FILE pointer or invoking a block with a file handle.

Arguments

  • name : string

  • mode : string

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

fio::fopen(name: string; mode: string) : FILE const?()
fio::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

fio::fread(f: file; buf: auto(BufType)) : auto()

Reads data from a file into a buffer, an array, or returns the full contents as a string, with block-based overloads available.

Arguments

  • f : file

  • buf : auto(BufType) implicit

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

Obsolete; saves the provided buffer data to a file in binary format.

Arguments

  • f : file

  • buf : auto(BufType)

fio::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

fio::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

fio::fstat(f: file) : FStat()
fio::fstderr() : FILE const?()

Returns the FILE pointer corresponding to the standard error stream.

fio::fstdin() : FILE const?()

Returns the FILE pointer corresponding to the standard input stream.

fio::fstdout() : FILE const?()

Returns the FILE pointer corresponding to the standard output stream.

fio::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

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

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

Arguments

  • f : file

  • buf : array<auto(BufType)> implicit

fio::fwrite(file: FILE const?; text: string)
fio::fwrite(f: file; buf: auto(BufType)) : auto()
fio::getchar() : int()

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

fio::remove(name: string) : bool()

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

Arguments

  • name : string implicit

fio::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

4.1.6.6. stat

fio::stat(path: string) : FStat()

Retrieves file metadata such as size and timestamps for the file at the given path, returning an FStat structure or populating one by reference.

Arguments

  • path : string

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

4.1.7. Path manipulation

fio::base_name(name: string) : string()

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

Arguments

  • name : string implicit

fio::dir_name(name: string) : string()

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

Arguments

  • name : string implicit

fio::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

4.1.8. Directory manipulation

fio::chdir(path: string) : bool()

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

Arguments

  • path : string implicit

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

Iterates over all entries in the directory at the given path, invoking the block with each filename.

Arguments

  • path : string

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

fio::getcwd() : string()

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

fio::mkdir(path: string) : bool()

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

Arguments

  • path : string implicit

fio::mkdir_rec(path: string) : bool()

Recursively creates the directory at the specified path along with any missing parent directories, returning true on success.

Arguments

  • path : string

4.1.9. OS specific routines

fio::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

fio::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

fio::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

fio::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

fio::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

fio::sanitize_command_line(var: string) : string()

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

Arguments

  • var : string implicit

fio::sleep(msec: uint)

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

Arguments

  • msec : uint

4.1.10. Dynamic modules

4.1.10.1. register_dynamic_module

fio::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

fio::register_dynamic_module(path: string; name: string; on_error: int) : void?()
fio::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