io
File and stream I/O — whole-file reads and writes, streaming handles, line iteration, filesystem queries, directory operations, globbing, tempfiles, and advisory file locking. Whole-file operations materialize content in memory; streaming handles and lazy iterators process arbitrary-size inputs with bounded memory. Path arguments resolve via cx-stdlib/path. Every function is impure and capability-gated: read or write access is checked at the effect point and denied by default.
io:read-file
[$io:read-file] -> string — Read an entire file as a UTF-8 string; raises on invalid UTF-8.
[?lib 'cx-stdlib/io']
[$io:read-file "/var/log/app.log"]
cx-err:CXER0271
io:read-file-bytes
[$io:read-file-bytes] -> bytes — Read an entire file as raw bytes, with no encoding check.
[?lib 'cx-stdlib/io']
[$io:read-file-bytes "/var/log/app.log"]
cx-err:CXER0271
io:read-file-lines
[$io:read-file-lines] -> [sequence string] — Read an entire file as a sequence of lines.
[?lib 'cx-stdlib/io']
[$io:read-file-lines "/var/log/app.log"]
cx-err:CXER0271
io:write-file
[$io:write-file] -> null — Create or truncate a file and write a string; atomic via tempfile rename on POSIX.
[?lib 'cx-stdlib/io']
[$io:write-file "/tmp/out.txt" "hello"]
cx-err:CXER0271
io:edit-file
[$io:edit-file] -> null — Surgical in-place file edit: read, replace `from` with `to` (it MUST occur exactly once, else [err cx-err:CXER2903] and no write), and write back. The in-CX equivalent of the harness Edit tool — needs both read and write capabilities.
[?lib 'cx-stdlib/io']
[$io:edit-file "/tmp/out.txt" "old" "new"]
cx-err:CXER0271
io:write-file-bytes
[$io:write-file-bytes] -> null — Create or truncate a file and write raw bytes.
[?lib 'cx-stdlib/bytes']
[?lib 'cx-stdlib/io']
[$io:write-file-bytes "/tmp/out.bin" [$bytes:from-string-utf8 "hi"]]
cx-err:CXER0271
io:write-file-lines
[$io:write-file-lines] -> null — Create or truncate a file and write a sequence of lines.
[?lib 'cx-stdlib/io']
[$io:write-file-lines "/tmp/out.txt" ("a", "b", "c")]
cx-err:CXER0271
io:append-file
[$io:append-file] -> null — Append a string to a file, creating it if absent.
[?lib 'cx-stdlib/io']
[$io:append-file "/tmp/out.txt" "more"]
cx-err:CXER0271
io:append-file-bytes
[$io:append-file-bytes] -> null — Append raw bytes to a file, creating it if absent.
[?lib 'cx-stdlib/bytes']
[?lib 'cx-stdlib/io']
[$io:append-file-bytes "/tmp/out.bin" [$bytes:from-string-utf8 "more"]]
cx-err:CXER0271
io:open
[$io:open] -> element — Open a file in the given mode and return a stream handle.
[?lib 'cx-stdlib/io']
[$io:open "/var/log/app.log" "r"]
cx-err:CXER0271
io:open-with-opts
[$io:open-with-opts] -> element — Open a file with an options map (mode, encoding, buffer size, line terminator, atomic) and return a stream handle.
[?lib 'cx-stdlib/io']
[$io:open-with-opts "/tmp/out.txt" [map mode="w" atomic=true]]
cx-err:CXER0271
io:close
[$io:close] -> null — Close a file handle; idempotent, so closing twice is safe.
[?lib 'cx-stdlib/io']
[$io:close [$io:open "/var/log/app.log" "r"]]
[granted-harness: open a real handle then close releases it]
io:read-bytes
[$io:read-bytes] -> bytes — Read up to n bytes from a stream handle.
[?lib 'cx-stdlib/io']
[$io:read-bytes [$io:open "/var/log/app.log" "r"] 16]
cx-err:CXER0271
io:read-line
[$io:read-line] -> string — Read one line from a stream handle, up to the line terminator; returns empty at EOF.
[?lib 'cx-stdlib/io']
[$io:read-line [$io:open "/var/log/app.log" "r"]]
cx-err:CXER0271
io:read-all
[$io:read-all] -> string — Read the remaining stream content as a string.
[?lib 'cx-stdlib/io']
[$io:read-all [$io:open "/var/log/app.log" "r"]]
cx-err:CXER0271
io:read-all-bytes
[$io:read-all-bytes] -> bytes — Read the remaining stream content as raw bytes.
[?lib 'cx-stdlib/io']
[$io:read-all-bytes [$io:open "/var/log/app.log" "r"]]
cx-err:CXER0271
io:write-bytes
[$io:write-bytes] -> null — Write raw bytes to a stream handle.
[?lib 'cx-stdlib/io']
[$io:write-bytes [$io:open "/tmp/out.bin" "w"] [$bytes:from-string "hi"]]
cx-err:CXER0271
io:write-string
[$io:write-string] -> null — Write a string to a stream handle.
[?lib 'cx-stdlib/io']
[$io:write-string [$io:open "/tmp/out.txt" "w"] "hi"]
cx-err:CXER0271
io:write-line
[$io:write-line] -> null — Write a string followed by a line terminator to a stream handle.
[?lib 'cx-stdlib/io']
[$io:write-line [$io:open "/tmp/out.txt" "w"] "hi"]
cx-err:CXER0271
io:flush
[$io:flush] -> null — Flush buffered writes on a stream handle to the underlying file.
[?lib 'cx-stdlib/io']
[$io:flush [$io:open "/tmp/out.txt" "w"]]
cx-err:CXER0271
io:seek
[$io:seek] -> null — Move the stream position to an offset relative to start, current, or end.
[?lib 'cx-stdlib/io']
[$io:seek [$io:open "/var/log/app.log" "r"] 0 :start]
cx-err:CXER0271
io:tell
[$io:tell] -> int — Report the current byte offset of a stream handle.
[?lib 'cx-stdlib/io']
[$io:tell [$io:open "/var/log/app.log" "r"]]
cx-err:CXER0271
io:is-eof
[$io:is-eof] -> bool — Report whether a stream handle has reached end of file.
[?lib 'cx-stdlib/io']
[$io:is-eof [$io:open "/var/log/app.log" "r"]]
cx-err:CXER0271
io:line-iter
[$io:line-iter] -> [iterator string] — Return a lazy, memory-bounded iterator over a handle's lines; closes the handle on exhaustion.
[?lib 'cx-stdlib/io']
[$io:line-iter [$io:open "/var/log/app.log" "r"]]
cx-err:CXER0271
io:exists
[$io:exists] -> bool — Report whether a path exists.
[?lib 'cx-stdlib/io']
[$io:exists "/var/log/app.log"]
cx-err:CXER0271
io:is-file
[$io:is-file] -> bool — Report whether a path is a regular file.
[?lib 'cx-stdlib/io']
[$io:is-file "/var/log/app.log"]
cx-err:CXER0271
io:is-directory
[$io:is-directory] -> bool — Report whether a path is a directory.
[?lib 'cx-stdlib/io']
[$io:is-directory "/var/log"]
cx-err:CXER0271
io:is-symlink
[$io:is-symlink] -> bool — Report whether a path is a symbolic link, without following it.
[?lib 'cx-stdlib/io']
[$io:is-symlink "/var/log/app.log"]
cx-err:CXER0271
io:stat
[$io:stat] -> element — Return a structured element of a path's size, type, timestamps, permissions, and ownership.
[?lib 'cx-stdlib/io']
[$io:stat "/var/log/app.log"]
cx-err:CXER0271
io:size
[$io:size] -> int — Return a file's size in bytes.
[?lib 'cx-stdlib/io']
[$io:size "/var/log/app.log"]
cx-err:CXER0271
io:modified-time
[$io:modified-time] -> datetime — Return a path's last-modified timestamp.
[?lib 'cx-stdlib/io']
[$io:modified-time "/var/log/app.log"]
cx-err:CXER0271
io:created-time
[$io:created-time] -> datetime — Return a path's creation timestamp.
[?lib 'cx-stdlib/io']
[$io:created-time "/var/log/app.log"]
cx-err:CXER0271
io:list-dir
[$io:list-dir] -> [sequence string] — List the entries of a directory.
[?lib 'cx-stdlib/io']
[$io:list-dir "/var/log"]
cx-err:CXER0271
io:make-dir
[$io:make-dir] -> null — Create a single directory.
[?lib 'cx-stdlib/io']
[$io:make-dir "/tmp/newdir"]
cx-err:CXER0271
io:make-dirs
[$io:make-dirs] -> null — Create a directory and any missing intermediate directories.
[?lib 'cx-stdlib/io']
[$io:make-dirs "/tmp/a/b/c"]
cx-err:CXER0271
io:remove
[$io:remove] -> null — Remove a single file.
[?lib 'cx-stdlib/io']
[$io:remove "/tmp/out.txt"]
cx-err:CXER0271
io:remove-dir
[$io:remove-dir] -> null — Remove an empty directory.
[?lib 'cx-stdlib/io']
[$io:remove-dir "/tmp/newdir"]
cx-err:CXER0271
io:remove-tree
[$io:remove-tree] -> null — Recursively delete a directory tree without following symlinks; refuses to delete a filesystem root.
[?lib 'cx-stdlib/io']
[$io:remove-tree "/tmp/a"]
cx-err:CXER0271
io:rename
[$io:rename] -> null — Rename or move a path from one location to another.
[?lib 'cx-stdlib/io']
[$io:rename "/tmp/a.txt" "/tmp/b.txt"]
cx-err:CXER0271
io:copy
[$io:copy] -> null — Copy a single file to a destination path.
[?lib 'cx-stdlib/io']
[$io:copy "/tmp/a.txt" "/tmp/b.txt"]
cx-err:CXER0271
io:copy-tree
[$io:copy-tree] -> null — Recursively copy a directory tree to a destination path.
[?lib 'cx-stdlib/io']
[$io:copy-tree "/tmp/a" "/tmp/b"]
cx-err:CXER0271
io:symlink
[$io:symlink] -> null — Create a symbolic link pointing at a target.
[?lib 'cx-stdlib/io']
[$io:symlink "/tmp/target" "/tmp/link"]
cx-err:CXER0271
io:readlink
[$io:readlink] -> string — Return the target a symbolic link points to.
[?lib 'cx-stdlib/io']
[$io:readlink "/tmp/link"]
cx-err:CXER0271
io:glob
[$io:glob] -> [sequence string] — Eagerly return all paths matching a glob pattern.
[?lib 'cx-stdlib/io']
[$io:glob "/var/log/*.log"]
cx-err:CXER0271
io:glob-iter
[$io:glob-iter] -> [iterator string] — Lazily yield paths matching a glob pattern on demand.
[?lib 'cx-stdlib/io']
[$io:glob-iter "/var/log/*.log"]
cx-err:CXER0271
io:walk
[$io:walk] -> [iterator element] — Lazily yield one dir-entry element per filesystem entry in recursive traversal order.
[?lib 'cx-stdlib/io']
[$io:walk "/var/log"]
cx-err:CXER0271
io:temp-file
[$io:temp-file] -> element — Create a fresh open temp file handle that auto-deletes on close.
[?lib 'cx-stdlib/io']
[$io:temp-file "pre" ".txt"]
cx-err:CXER0271
io:temp-dir
[$io:temp-dir] -> string — Create a fresh empty temp directory and return its path; the caller cleans it up.
[?lib 'cx-stdlib/io']
[$io:temp-dir "pre"]
cx-err:CXER0271
io:system-temp-dir
[$io:system-temp-dir] -> string — Return the operating system's temp directory path.
[?lib 'cx-stdlib/io']
[$io:system-temp-dir]
cx-err:CXER0271
io:lock
[$io:lock] -> element — Acquire a shared or exclusive advisory lock on a file handle.
[?lib 'cx-stdlib/io']
[$io:lock [$io:open "/tmp/out.txt" "w"] :exclusive]
cx-err:CXER0271
io:unlock
[$io:unlock] -> null — Release a lock held on a file handle.
[?lib 'cx-stdlib/io']
[$io:unlock [$io:open "/tmp/out.txt" "w"]]
cx-err:CXER0271
io:watch
[$io:watch] -> element — Start a recursive OS filesystem watch (inotify / FSEvents) on a directory and return a watch handle. Real continuous notification, not polling.
[?lib 'cx-stdlib/io']
[$io:watch "/tmp/project"]
cx-err:CXER0271
io:watch-next
[$io:watch-next] -> element — Block until the next change under a watch handle and return [change path=… op=created|modified|deleted]. With an optional timeout (ms) returns absence on expiry. An [change op=overflow] means the OS dropped events under load — rescan the tree.
[?lib 'cx-stdlib/io']
[$io:watch-next [$io:watch "/tmp/project"] 1000]
cx-err:CXER0271
io:watch-close
[$io:watch-close] -> null — Tear down a watch handle and unblock any watch-next currently parked on it. Idempotent.
[?lib 'cx-stdlib/io']
[$io:watch-close [$io:watch "/tmp/project"]]
cx-err:CXER0271