From a059eda0ecd73cbb6277da3bf64a550097bc346d Mon Sep 17 00:00:00 2001
From: kitty <nepeta@canaglie.net>
Date: Sun, 29 Mar 2026 20:23:28 +1100
Subject: DEFER-ed words in core, file open/read/write/close

---
 readme.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

(limited to 'readme.md')

diff --git a/readme.md b/readme.md
index 0b89015..73af8a2 100644
--- a/readme.md
+++ b/readme.md
@@ -8,6 +8,7 @@ documentation and will be obvious or documented in the description.
 
 - `a`: memory address
 - `c`: one byte value
+- `e`: error code
 - `n`: signed integer
 - `u`: unsigned integer
 - `z`: null-terminated string
@@ -63,6 +64,11 @@ which simply pushes the address following the definition to the stack.
 this messes with the return stack and is not meant to be called
 outside of its specific context.
 
+### `(defer)   ( -- )`
+activate a deferred word from the address following this word's call.
+this messes with the return stack and is not meant to be called
+outside of its specific context.
+
 ### `(does>)   ( -- )`
 run non-default behaviour of a `create`d word.
 pushes the data location onto the stack and calls the word
@@ -171,6 +177,13 @@ return true if n1 is greater than or equal to n2.
 ### `>body   ( ht -- xt )`
 yield the code field of header token.
 
+### `>errno   ( u -- val err )`
+transform the result of a system call into a value/error pair.
+if no error occured, err is zero and val is the result,
+if an error has occurred, val is zero and
+err is a negative integer
+(the exact value depends on the error)
+
 ### `>in   ( -- a )`
 variable containing the index of the first unparsed character
 in the input buffer.
@@ -283,6 +296,9 @@ transform an amount of cells into an amount of bytes.
 ### `char   ( "c" -- c )`
 yield the value of the first character of the next word in the input stream.
 
+### `close-file   ( fd -- e )`
+close the file at fd.
+
 ### `cmove   ( a1 a2 u -- )`
 copy u bytes of memory from a1 to a2.
 bytes are copied in low memory to high memory order.
@@ -434,6 +450,11 @@ and no number is provided.
 ### `octal   ( -- )`
 set current base to octal.
 
+### `open-file   ( z mode -- fd e )`
+open the given file with the given mode (probably r/w, r/o or w/o)
+and yield the resulting file descriptor
+note that this word uses the pad.
+
 ### `or  ( u1 u2 -- u )`
 perform bitwise OR on u1 and u2.
 
@@ -487,6 +508,10 @@ move a value from the return stack to the working stack.
 ### `rdrop   ( R: u -- )`
 remove the value at the top of the return stack.
 
+### `read-file   ( a u fd -- u' e )`
+read u bytes from fd into memory location a.
+u' is the number of bytes read.
+
 ### `repeat   ( -- ) IMMEDIATE COMPILE-ONLY`
 in a begin-while-repeat loop, loop back to the condition.
 
@@ -637,6 +662,10 @@ a constant, meaning 'write only', used for file I/O.
 if given flag is true, continue the current begin-while-repeat loop,
 otherwise branch to after.
 
+### `write-file   ( a u fd -- u' e )`
+write u bytes from a into fd.
+u' is the number of bytes written.
+
 ### `xor   ( u1 u2 -- u )`
 perform bitwise XOR on u1 and u2.
 
-- 
cgit v1.2.3