std.fs.writeBytes

Each function accepts a string path or a Path. Strings use the host path syntax. A Path supplies its normalized relative text. Relative paths use the working directory in an ordinary installed CLI invocation. A package host applies its configured filesystem base and capability policy.

Path and payload arguments are evaluated once in source order before the operation starts. The operation acquires and releases its own resources before returning. It does not change a separately opened File cursor.

Empty paths and paths containing NUL return Err containing a string. Missing read targets, incorrect path kinds, permission denial, package capability denial, and host failures use the same error channel. Errors are values. They do not terminate the program unless the caller chooses to propagate or assert them.

An error string identifies the public operation and the supplied path. It also describes the failure condition. Platform wording, operating system error numbers, and localized explanations are not stable API values.

readText returns the entire regular file as text. UTF-8 validity and text preservation follow UTF-8 decoding →. Empty files return an empty string. Invalid UTF-8 returns Err without a decoded text value.

readBytes returns every byte in order, including zero bytes and bytes that are not valid UTF-8. Empty files return empty Bytes. Reading does not create or modify the file.

writeText encodes its string as UTF-8. writeBytes writes the supplied bytes unchanged. Both create a missing regular file or replace the full contents of an existing regular file. An empty payload creates or truncates the file to zero bytes. No newline or byte order mark is added.

Writes do not create missing parent directories. They follow the host permission and creation policy. Replacing a file with shorter content removes its previous suffix. Success returns Ok(()) after all payload bytes have been accepted.

A write failure may occur after creation, truncation, or a prefix write. Err does not promise rollback, atomic replacement, or persistence across a system crash. Earlier argument effects remain visible.

list returns immediate children sorted by their exact names in ascending Unicode scalar order. It does not return dot or parent pseudoentries, traverse child directories, normalize Unicode names, or fold case. The name field contains the child name without the parent path.

Each entry kind is exactly file, directory, symlink, or other. Classification uses the entry itself and does not follow a symbolic link. For a regular file, sizeBytes is Some of its byte length when that length fits in int. Other kinds and an unrepresentable size use None().

A name that cannot be represented as Unicode, a failure while reading an entry, or a failure obtaining its metadata returns Err for the whole list. No partial array is returned. Separate operations do not provide a filesystem snapshot, so other processes may change a path between calls.

Host access follows symbolic links where the operation addresses their target, subject to host capability checks. A normalized Path is not an authorization token. Use File when operations must retain one open resource and cursor, and std.fs when the operation concerns complete contents or directory entries.