From 2a24b0a3fc3c4986572ae2c4ea0e8e387497a7f6 Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
Date: Sun, 23 Nov 2025 14:19:04 -0500
Subject: Add `at_cleanup()` function

---
 api/api.md | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

(limited to 'api/api.md')

diff --git a/api/api.md b/api/api.md
index 02ad054e..5c9dc9c4 100644
--- a/api/api.md
+++ b/api/api.md
@@ -32,11 +32,35 @@ force_tty | `Bool` | Whether or not to force the use of /dev/tty.  | `yes`
 ```tomo
 assert ask("What's your name? ") == "Arthur Dent"
 
+```
+## at_cleanup
+
+```tomo
+at_cleanup : func(fn: func() -> Void)
+```
+
+Register a function that runs at cleanup time for Tomo programs. Cleanup time happens when a program exits (see `atexit()` in C), or immediately before printing error messages in a call to `fail()`. This allows for terminal cleanup so error messages can be visible as the program shuts down.
+
+Use this API very carefully, because errors that occur during cleanup functions may make it extremely hard to figure out what's going on. Cleanup functions should be designed to not error under any circumstances.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+fn | `func()` | A function to run at cleanup time.  | -
+
+**Return:** Nothing.
+
+
+**Example:**
+```tomo
+at_cleanup(func()
+    (/tmp/file.txt).remove(ignore_missing=yes)
+)
+
 ```
 ## exit
 
 ```tomo
-exit : func(message: Text? = none, status: Int32 = Int32(1) -> Void)
+exit : func(message: Text? = none, status: Int32 = Int32(1) -> Abort)
 ```
 
 Exits the program with a given status and optionally prints a message.
-- 
cgit v1.2.3