std: File, the first user of drops: std.Host.open(path, mode) returns an owned std.File (or null) with write and read, and its drop closes the descriptor; Host.writefile is built on it; file_drop.zc, learn and readme

1 files changed, 2 insertions, 0 deletions

diff --git a/docs/LEARN.md b/docs/LEARN.md
index fd399e3..ed12caf 100644
--- a/docs/LEARN.md
+++ b/docs/LEARN.md
@@ -535,6 +535,8 @@ output:
 
 `rt.syscall(op, a, b, c)` calls the runtime interface to the vm's syscall gate. the runtime defines names such as `SYS_OPEN`, `SYS_READ`, `SYS_WRITE`, `SYS_GETENV`, and `SYS_TIME`. unsupported operations return -1. `std.Host.now()` wraps the clock request.
 
+`std.Host.open(path, mode)` opens a file (0 to read, 1 to write) and returns an owned `std.File`, or null. `f.write(s)` and `f.read(buf, n)` go through its descriptor, and its drop closes it: the file is closed when its owner's block ends, when it is freed, or when the collector reclaims it, with no `close` to call.
+
 `std.Host.env(name, dst, n)` writes an environment value into a word-string buffer and returns its length, or -1 when it is unset. the library also supplies `std.argc`, `std.argv`, `std.envc`, and `std.envp`; a program read on stdin has `<eval>` as its first argument. gate calls must be made from ordinary code, outside an `o3` region.
 
 [example source](../examples/learn/21-host.zc):