File, Dir and Path
Every file function takes a timeout in milliseconds and returns a Result. It defaults to 30000 and may be left out. File.open also defaults its mode to "read", and File.each_line and File.foreach default buffer_bytes to 65536.
- Text is UTF-8. One text call reads or writes at most 1 MiB (
File.sha256streams bytes and has no cap). Files have the permissions of the user who runs the program. - With
--deny-fs(or--sandbox), every call on this page exceptPath.join, andLazy.write_linesandLazy.write_bytes, returns an error that begins withdenied: --deny-fs. - Regular files use a pool of 4 threads, shared with DNS lookups and TLS certificate loading, so calls wait for a free thread when many run. Raise it (at most 1024) before the program starts:
UV_THREADPOOL_SIZE=16 agentica app.agc. - Pipes, FIFOs and terminals skip the pool and wait on the event loop, so their timeout always ends the wait.
File.read_textof a pipe reads until the writer closes it. - File calls accept regular files and symbolic links to them, and also FIFOs, pipes and devices that can wait. They reject directories, a missing path for a read, and a path that reopens a pipe the VM made for itself.
Fileis a reserved name, with the membersFile.HandleandFile.Info; a file handle is opaque.
File.write_text #
File.write_text(path: String, text: String, timeout_ms: Int = 30000) -> Result[Void]Creates or replaces a file with the text.
def main() -> Void
r = File.write_text("notes.txt", "first line\n", 1000)
puts(r)
endok()File.replace #
File.replace(path: String, data: Bytes, timeout_ms: Int = 30000) -> Result[Void]Replaces an existing regular file with at most 16 MiB of bytes in one step, so a reader sees the old file or the new one, never a part or no file. Use it to save a file that people edit, as agentica fmt does.
def main() -> Void
r = File.replace("notes.txt", "second draft\n".bytes, 1000)
puts(r)
end- The bytes go to a new file in the same folder, which only the owner can read while it is written; it then takes the old file’s permission bits, is flushed to the disk and is renamed over it. A failure removes the new file and leaves the old one as it was. A process killed during the write can leave a hidden
.agc-PID-N.tmpfile in the folder. Writing needs write permission on the folder. - A symbolic link is followed and stays a link: the file it points to is replaced. The new file belongs to the user who runs the program, and a hard link to the old file keeps the old bytes.
- The file must exist and be a regular file: a missing path is
error("filesystem: cannot resolve path ..."), a directory or a FIFOerror("filesystem: path does not refer to a regular file"). UseFile.write_textto create a file. - On Windows a read-only file is an error, and nothing is written. Of the old file’s attributes only the read-only bit is kept: the access list comes from the folder, and the hidden and system attributes are dropped.
File.append_text #
File.append_text(path: String, text: String, timeout_ms: Int = 30000) -> Result[Void]Adds text at the end of a file. It creates the file when it is missing.
File.read_text #
File.read_text(path: String, timeout_ms: Int = 30000) -> Result[String]Reads a whole file as text.
def main() -> Void
case File.read_text("notes.txt", 1000)
ok(text) -> puts("#{text.strip.split("\n").size} lines")
error(message) -> IO.warn("cannot read: #{message}")
end
endFile.sha256 #
File.sha256(path: String, timeout_ms: Int = 30000) -> Result[Bytes]Hashes a whole file with SHA-256 and returns the 32 digest bytes as a Bytes, the same bytes OpenSSL.Digest.sha256 gives for the same content; OpenSSL.Digest.hexencode writes them as hex. It streams the file in 64 KiB chunks, so a file far over the 1 MiB text cap still hashes.
def main() -> Void
case File.sha256("notes.txt", 1000)
ok(digest) -> puts(OpenSSL.Digest.hexencode(digest))
error(message) -> IO.warn("cannot hash: #{message}")
end
end- Only regular files are hashed; symbolic links are followed. A missing path, a directory, a FIFO, pipe or device give
error("filesystem: path does not refer to a regular file"), asFile.read_textdoes. timeout_mscovers the whole call and must be positive, otherwiseerror("filesystem: timeout must be positive milliseconds"). When it runs out the call returnserror("filesystem: operation timed out")and a running hash is dropped. A cancelled task detaches the same way.- There is no snapshot: a concurrent writer changes the digest. To verify a download, write it to a temporary name, hash it, then
Path.renameit into place.
File.stat #
File.stat(path: String, timeout_ms: Int = 30000) -> Result[File.Info]Gives a File.Info: kind, size_bytes, modified_seconds, mode, user_id, group_id. A symbolic link is followed.
kindis Ruby’sFile::Stat#ftypename:"file"(a regular file only),"directory","fifo","socket","characterSpecial"(such as/dev/null),"blockSpecial"or"unknown". Windows gives"file","directory","link"(File.lstatof a reparse point) and"characterSpecial"forNUL. Checkkind == "file"before reading a path you did not make: a read of a FIFO can wait for a writer.modeis the permission bits as anInt, with setuid, setgid and sticky:rw-------is 384 (octal 600).Windows has no Unix bits or owner ids:
modeis only the read-only attribute (438 writable, 292 read-only; it says nothing about the ACL), anduser_idandgroup_idare always 0, which is not the owner.
def main() -> Void
info = File.stat("notes.txt", 1000).unwrap!
puts("#{info.kind}: #{info.size_bytes} bytes, mode #{info.mode}")
endFile.lstat #
File.lstat(path: String, timeout_ms: Int = 30000) -> Result[File.Info]Like File.stat, but a symbolic link is not followed: kind is "link", size_bytes is the length of the link text, the other fields are the link’s own.
File.open and File.close #
File.open(path: String, mode: String = "read", timeout_ms: Int = 30000) -> Result[File.Handle]
File.close(handle: File.Handle, timeout_ms: Int = 30000) -> Result[Void]Opens a file for streaming.
| Mode | Meaning |
|---|---|
"read" | read an existing file |
"write" | create the file, or empty it |
"append" | write at the end of the file |
"create_private" | a new file that only you can read and write |
"create_private" fails when the path exists (a dangling link too) and never follows a link, so another user cannot redirect the write. Unix: mode 0600, less where the umask clears bits. Windows: a protected DACL that grants only the current user; creation fails unless the opened object has that owner and DACL.
close writes pending data. Closing twice is fine. Timeouts are positive milliseconds and include the wait for the handle’s lock: a timeout during active I/O closes the handle, and a timeout while waiting for the lock keeps it open.
- A file belongs to the task that opened it and closes, with its data written, when that task ends.
Task.awaitof that task returns after a regular file’s data is written (not a flush to a FIFO or a pipe), so a parent that awaits a helper reads everything it wrote. Acloseon a file already closing waits for that close. - At program end the run waits for open files to be written and for
putsandIO.warnoutput to reach its pipe or file, at most 30 seconds (--flush-timeout MSorAGENTICA_FLUSH_TIMEOUT_MS; the flag wins). When time runs out the exit code stays and stderr gets one line saying file data may not be written. - On
SIGINT,SIGTERM,SIGHUP,SIGUSR1orSIGUSR2that the program has not subscribed to (System.subscribe): child programs stop first, then files are written, then the program ends by that signal.SIGQUITdoes the same and exits with 131, without a core dump. A second signal ends it at once, once the children have stopped. Underagentica, Ctrl-C reaches the program directly;agenticawaits 2 seconds, sendsSIGTERM, waits 2 more, then kills it. - A path that reopens one of the program’s own internal pipes, or the descriptor behind stdout or stderr (
/proc/self/fd/5), giveserror("filesystem: path does not refer to a regular file"). Pipes the program got at start (stdin, stdout, stderr, a shell<(...)) open by path. - Windows: file calls accept only regular files (and folders where a folder is meant); a named pipe or a device is refused at once.
def main() -> Void
file = File.open("out.txt", "write", 1000).unwrap!
_ = File.write(file, "hello\n", 1000)
closed = File.close(file, 1000)
puts(closed.ok?)
endFile.open with a block #
File.open(path: String, mode: String = "read", timeout_ms: Int = 30000) do |file| ... end -> Result[T]Opens the file, calls the block with the handle, closes the handle with File.close(file, timeout_ms) when the block ends, and gives the block’s Result. Use it to read or write a file through a handle; open and close a handle by hand only when it must outlive one block, such as one shared with tasks.
def main() -> Void
r = File.open("out.txt", "write", 1000) do |file|
try File.write(file, "hello\n")
try File.write(file, "world\n")
ok(2)
end
puts(r)
end- The block gives a
Result[T], andtryworks in it.Tcomes from the expected type of the call (r: Result[List[String]] = File.open(...) do ...), or else from the block. A block that never givesok(it only giveserror(...)) fixes noT, and theerror(...)in the block isCHECK-RESULT-TYPEuntil the variable has a type:r: Result[Int] = File.open(...) do ... end. timeout_mslimits the open and the close, each on its own; it does not limit the block, so the whole call can take longer thantimeout_ms. Calls inside the block take their own timeouts.- If the open fails, the block does not run and the call gives the open error.
- The handle is closed whether the block gives
okorerror, an earlyreturnand a failedtryincluded. Afterok(value)the call givesok(value), or the close error if the close fails: the close writes pending data, so its error matters. After an error the call gives the block’s error and drops a close error. - A runtime error in the block ends the task, and the handle closes with the task, as above. A handle kept after the block (returned in the
Result) is closed: a call on it giveserror("filesystem: file handle is closed").
File.write and File.flush #
File.write(handle: File.Handle, text: String, timeout_ms: Int = 30000) -> Result[Void]
File.flush(handle: File.Handle, timeout_ms: Int = 30000) -> Result[Void]write adds text to an open file. flush sends what is buffered to the disk.
def save_lines(path: String, lines: List[String]) -> Result[Void]
file = try File.open(path, "write", 1000)
for line in lines
try File.write(file, line + "\n", 1000)
end
try File.flush(file, 1000)
File.close(file, 1000)
end
def main() -> Void
puts(save_lines("list.txt", ["a", "b"]))
endFile.try_lock #
File.try_lock(handle: File.Handle, timeout_ms: Int = 30000) -> Result[Bool]Takes an exclusive lock on the open file, without waiting. ok(true) means it is yours (also if this handle already holds it), ok(false) that another handle or process holds it.
- It ends when the handle closes, the opening task ends, or the program ends, even if killed. A
Process.spawnchild does not keep it. There is no unlock call. - Unix: advisory (
flock), so it stops only code that asks too. Windows:LockFileExon the whole range, and the OS rejects reads and writes through other handles. - Any handle mode works. Only a regular file can be locked (a pipe, FIFO or
/dev/nullis an error).
def main() -> Void
file = File.open("app.lock", "append", 1000).unwrap!
if File.try_lock(file, 1000).unwrap!
puts("running alone")
else
puts("another copy is running")
end
_ = File.close(file, 1000)
endFile.read_line #
File.read_line(handle: File.Handle, timeout_ms: Int = 30000) -> Result[String]Reads one line without its line ending (LF or CRLF; a final line without one counts). The text is strict UTF-8. At the end of the file, or on invalid UTF-8, it gives an error result. Loop with while line.ok?, or use File.each_line.
File.each_line #
File.each_line(path: String, buffer_bytes: Int = 65536, timeout_ms: Int = 30000) do |line| ... end -> Result[Void]Calls the block with each line, without its line ending (LF and CRLF; a last line without one is passed too). The file is never read whole, so a file larger than memory works, and so do FIFOs and pipes. The file closes on every way out.
- The block returns a
Result[Void]:ok()goes on, anerror(...)stops and is the result.tryandreturn error(...)work in the block. buffer_bytesis the longest line, counting its ending: 1024 to 16777216, elseRUNTIME-INVALID-COUNTbefore the file opens. A longer line ends the call witherror("filesystem: line exceeds buffer_bytes").timeout_mslimits each read, the open and the close, not the whole call. It must be positive, otherwiseerror("filesystem: timeout must be positive milliseconds"). A silent pipe ends the call with an error.- The text is strict UTF-8: invalid bytes end the call with an error.
- For a chain of steps over the lines (
select,map,first(n)…), useFile.foreach, aLazy[String]with the same reads. To write the lines of aLazy[String]to a file, usewrite_lines.
def main() -> Void
r = File.each_line("notes.txt", 4096, 1000) do |line|
return error("comment found: #{line}") if line.start_with?("#")
ok()
end
puts(r)
endFile.read_bytes and File.write_bytes #
File.read_bytes(handle: File.Handle, max_bytes: Int, timeout_ms: Int = 30000) -> Result[Bytes]
File.write_bytes(handle: File.Handle, bytes: Bytes, timeout_ms: Int = 30000) -> Result[Void]Both take and give a Bytes. read_bytes reads 1 to 1048576 bytes and gives empty bytes at the end of the file; write_bytes writes at most 1048576 bytes per call.
def main() -> Void
out = File.open("data.bin", "write", 1000).unwrap!
_ = File.write_bytes(out, Bytes.from_list([0, 1, 255]).unwrap!, 1000)
_ = File.close(out, 1000)
input = File.open("data.bin", "read", 1000).unwrap!
puts(File.read_bytes(input, 16, 1000).unwrap!.to_a)
end[0, 1, 255]Dir.list #
Dir.list(path: String, timeout_ms: Int = 30000) -> Result[List[String]]Gives the names in a directory, sorted.
def main() -> Void
for name in Dir.list(".", 1000).unwrap!
puts(name)
end
endDir.mkdir #
Dir.mkdir(path: String, timeout_ms: Int = 30000) -> Result[Void]Creates a directory and any missing parents. An existing directory is fine.
Dir.mkdir_private #
Dir.mkdir_private(path: String, timeout_ms: Int = 30000) -> Result[Void]Creates one directory that only you can enter, for a scratch directory in a shared place such as /tmp. It makes no parents, and an existing path is an error, so success means the directory is new and yours. Unix: mode 0700, less where the umask clears bits. Windows: the owner-and-DACL check of File.open.
def main() -> Void
name = "/tmp/app-#{Random.int(0, 999999999)}"
case Dir.mkdir_private(name, 1000)
ok(_) -> puts("made #{name}")
error(message) -> IO.warn("cannot make it: #{message}")
end
endPath.join #
Path.join(list: List[String]) -> Result[String]Joins parts with the separator of the system.
def main() -> Void
puts(Path.join(["build", "reports", "a.txt"]))
endok("build/reports/a.txt")Path.cwd and Path.resolve #
Path.cwd() -> Result[String]
Path.resolve(path: String) -> Result[String]cwd gives the current directory. resolve makes an absolute path, without following links. Neither ends in / except at a root; resolve keeps a trailing / only when the path ends in one.
Path.real #
Path.real(path: String) -> Result[String]Like POSIX realpath: the absolute path with every symbolic link resolved and ., .. and repeated separators removed. Unlike resolve, it reads the disk, so the path must exist (a missing path, a link loop or a non-directory is an error). A relative path starts at the working directory, and .. after a link follows the link’s target. An empty path or one with NUL is the same filesystem: invalid path error as File.stat. The VM puts no buffer limit on the path; the system’s own limit applies to its absolute form. Invalid UTF-8 bytes become U+FFFD. It has no timeout; it runs in the file pool and does not stop other tasks.
The system’s own rules show through:
- macOS fails a path of 1024 bytes or more, and accepts a
/after a file (file/gives the file); Linux and Windows give an error for it. - Windows removes
.and..from the typed text before it follows a link, solink/..is the folder that holds the link andmissing/..is not an error. A name under a file gives ENOENT (Linux and macOS: ENOTDIR). The result starts with a drive letter (/is the drive of the working directory, such asC:/). The binary opts in to long paths in its manifest. A path of 260 characters or more works only when the machine setsLongPathsEnabledto 1; otherwise it is an error, as isDir.mkdirof one.
def main() -> Void
puts(Path.real("/"))
puts(Path.real("/does/not/exist").ok?)
endok("/")
falsePath.remove #
Path.remove(path: String, timeout_ms: Int = 30000) -> Result[Void]Deletes a file, a symbolic link, or a directory with everything in it. A missing path gives ok().
- It never follows a link: a link is deleted itself, and what it names is left alone.
- It refuses a filesystem root, a trailing separator,
.and..(also as the end ofdir/..), and a tree more than 128 levels deep (left partly deleted). - A failed call keeps what it already deleted; the error names the failing entry with the system error. A timeout gives an error but the started removal runs to its end.
- A path under a file (
file/child) is an error (Not a directory), and so is a trailing separator on a symbolic link:link/must never reportok(). A failure inside the tree names the entry that failed. - Unix crosses mount points, as
rm -rfdoes. Windows removes junctions and other reparse points themselves without traversing them, refuses drive or share roots, alternate-data-stream syntax and components ending in a dot or space.
def main() -> Void
puts(Path.remove("build", 5000))
puts(Path.remove("old.log", 1000))
endPath.rename #
Path.rename(from: String, to: String, timeout_ms: Int = 30000) -> Result[Void]Renames a file, a symbolic link or a directory to a path that does not exist yet, in one step.
- It never replaces anything: when
toexists (even an empty directory) the call fails and nothing changes, so two programs racing for a name have exactly one winner. - A symbolic link moves as a link.
- Both paths must be on one file system; there is no copy fallback. Linux uses
renameat2withRENAME_NOREPLACE, macOSrenameatx_npwithRENAME_EXCL, and WindowsMoveFileExWwith no flags, so it neither replaces a target nor copies across volumes.
def main() -> Void
_ = Dir.mkdir_private("/tmp/job-new", 1000)
claimed = Path.rename("/tmp/job-new", "/tmp/job", 1000)
puts(claimed.ok?)
end