From 8682553498d32d3c18dea41c598ab40de18404a3 Mon Sep 17 00:00:00 2001
From: user <user@clank>
Date: Thu, 16 Jul 2026 07:30:34 +0200
Subject: tools: wc, head, and an argc/argv demo (args) + libc.c helpers

- c/libc.c: shared C helpers linked into every program - putu (print decimal),
  atou (parse decimal), argv_parse (tokenize getargs() into argc/argv).
- wc: count lines/words/chars of stdin. head [n]: first n lines (drains rest to
  EOF). args: argc/argv demo.
- pid now uses libc putu; build.sh links libc.c; Makefile CBLOBS + libc dep.
- README: document the new tools + argv_parse.
- verified: 'args one two three' -> argc=3/argv[..]; wc '2 3 16'; head 2.
---
 README.md | 39 +++++++++++++++++++++++++++------------
 1 file changed, 27 insertions(+), 12 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index c386c08..84c5c72 100644
--- a/README.md
+++ b/README.md
@@ -195,11 +195,19 @@ void main(void) {
 
 ### libc
 
-`writes`, `putc`, `puts`, `nl`, `strlen`, `readc` (returns `EOF`=4 at end of
-input), `getargs` (this program's argument string), `getpid`, `sexit`.
+Syscall wrappers (`c/libc.s`): `writes`, `putc`, `puts`, `nl`, `strlen`, `readc`
+(returns `EOF`=4 at end of input), `getargs` (this program's argument string),
+`getpid`, `sexit`. C helpers (`c/libc.c`, linked into every program): `putu`
+(print decimal), `atou` (parse decimal), `argv_parse` (tokenize into argc/argv).
+
 Arguments: the shell splits the command line at the first space and leaves
-`"cmd\0args\0"` at `$A000`; the child inherits it through `fork`, and
-`getargs()` returns the args.
+`"cmd\0args\0"` at `$A000`; the child inherits it through `fork`, `getargs()`
+returns the raw arg string, and `argv_parse()` tokenizes it:
+
+```c
+char *argv[8];
+unsigned char argc = argv_parse(argv, 8);   /* args one two -> argc=3 */
+```
 
 ### CLI tools (in `c/`)
 
@@ -207,21 +215,27 @@ Arguments: the shell splits the command line at the first space and leaves
 |------|--------------|
 | `echo` | print its arguments (`echo hello world`) |
 | `cat`  | copy stdin to stdout until EOF (Ctrl-D / pipe end) |
+| `wc`   | count lines / words / chars of stdin |
+| `head` | print the first *n* lines of stdin (`head 5`, default 10) |
+| `args` | argc/argv demo (`args one two three`) |
 | `uname`| print the system name |
 | `pid`  | print the process's pid (decimal) |
 | `true` / `false` | exit 0 / 1 |
 | `chello` | the C "hello" demo |
 
 ```
-$ uname
-gbos sm83 (Game Boy Color)
 $ echo C tools on a Game Boy
 C tools on a Game Boy
-$ pid
-5
-$ cat
-hi from cat
-hi from cat
+$ args one two three
+argc=3
+argv[0]=one
+argv[1]=two
+argv[2]=three
+$ wc          (input: "hello world\nfoo\n")
+2 3 16
+$ head 2      (input: alpha/beta/gamma/delta)
+alpha
+beta
 ```
 
 Each tool is a separate `c/<name>.c`, built to a ROM-bank blob, INCBIN'd, and
@@ -244,7 +258,8 @@ explicit lengths and emit newlines via `nl()`.
 - [x] grow libc (`puts`/`putc`/`strlen`/`getargs`/EOF) + args via the shell
 - [x] CLI tools in C: `echo`, `cat`, `uname`, `pid`, `true`, `false`
 - [x] Makefile builds all C programs (a `CBLOBS` list)
-- [ ] more tools (`wc`, `head`, `rev`), a real `argc/argv`, a RAM filesystem
+- [x] `wc`, `head`, and an `argc/argv` demo (`args`) + `argv_parse` in libc
+- [ ] more tools (`rev`, `grep`), option parsing (`-n`), a RAM filesystem
 - [ ] Preemptive scheduling: real context save in `TimerISR` → `hSwitchTo`
 - [ ] Use the `$D000-$DFFF` u-area (SVBK) for per-process kernel state / kstack
 - [ ] `brk`/heap allocator inside the task bank (heap up, stack down, collision = ENOMEM)
-- 
cgit v1.3.1-sl0p