libc: FILE* v2 — буферизация потоков (вариант B+)

- единый ленивый буфер BUFSIZ=512 на чтение и запись с
  автопереключением направления (_F_DIROUT, _file_sync: запись
  сбрасывается write()-ом, readahead откатывается lseek-ом)
- статическая таблица OPEN_MAX=8 слотов вместо malloc для FILE;
  _fclosall через atexit — exit() сбрасывает несброшенную запись
- fread/fwrite: мелкое через буфер (memcpy), блоки >= BUFSIZ — мимо
  буфера одним syscall; горячие пути fgetc/fputc и сканер строк
  fgets (LDI до '\n') — на asm, SDCC на эти цепочки генерит ~90
  инструкций с IX-фреймом
- новое: ungetc (1 байт через hold, работает и на stdin),
  fprintf/vfprintf (vsprintf+fwrite), fflush(NULL) = все потоки
- фиксы stdio-review: fwrite ставит _F_ERROR при короткой записи
  (issue 3), fgets(n=1) возвращает пустую строку (issue 4)
- замер (MAME, HDD, 100 КБ): небуферизованная оценка ~144 с →
  fgetc 5 с (×29), fgets ~1 с; дизайн и отвергнутые варианты —
  docs/file-buffering-design.md

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

libc/include/stdio.h

@@ -1,15 +1,20 @@
 /*
- * stdio.h — extends SDCC's z80 stdio with a minimal FILE * stream API.
+ * stdio.h — extends SDCC's z80 stdio with a buffered FILE * stream API.
  *
  * The bottom of the stack is the existing POSIX-style fd I/O (open/
- * read/write/close/lseek).  FILE * is a thin struct wrapping a fd plus
- * a few flag bits.  No buffering — every fread/fwrite/fputc maps 1:1
- * to a syscall.  Sprinter's I/O is already char-oriented at the ESTEX
- * level, so this stays minimal.
+ * read/write/close/lseek).  FILE * adds a per-stream 512-byte buffer,
+ * lazily malloc'ed on first buffered operation, shared between reading
+ * (readahead) and writing (accumulation) with automatic direction
+ * switching — see docs/file-buffering-design.md (variant B+).
+ *
+ * FILE objects live in a static table of OPEN_MAX slots (no malloc);
+ * a slot is free when flags == 0.  exit() flushes and closes all open
+ * streams via an atexit-registered _fclosall (armed by first fopen).
  *
  * stdin / stdout / stderr are predefined "virtual" FILE * pointers
- * that talk to the console via putchar()/getchar() (NOT through a fd).
- * That keeps printf-routed output going through our CR/LF mapping.
+ * that talk to the console via putchar()/getchar() (NOT through a fd)
+ * and are never buffered.  That keeps printf-routed output going
+ * through our CR/LF mapping.
  */
 
 #ifndef STDIO_H
@@ -34,18 +39,34 @@ char puts   (const char *);
 int  putchar(int);
 int  getchar(void);
 
-/* ---- FILE * (minimal, unbuffered) ---------------------------------- */
+/* ---- FILE * (buffered, variant B+) --------------------------------- */
 
-/* Internal layout — opaque to user.  fd == -1 marks the console
- * pseudo-streams (stdin/stdout/stderr). */
+/* Максимум одновременно открытых fopen-потоков (консольные псевдо-
+ * потоки не в счёт).  DSS сам ограничивает число манипуляторов
+ * (ошибка 06h "Too many open files"); наша таблица зеркалит его. */
+#define OPEN_MAX   8
+#define FOPEN_MAX  OPEN_MAX
+
+/* Размер ленивого буфера потока. */
+#define BUFSIZ     512
+
+/* Internal layout — opaque to user.  Слот таблицы свободен, когда
+ * flags == 0.  level — число байт: непрочитанный readahead (направление
+ * «чтение») либо ещё не сброшенная запись (направление «запись»,
+ * флаг _F_DIROUT). */
 typedef struct __FILE {
-    int     fd;          /* underlying POSIX fd, or -1 for console */
-    uint8_t flags;       /* see _F_* below */
+    int      fd;         /* POSIX fd (манипулятор DSS) */
+    uint8_t  flags;      /* см. _F_* ниже; 0 = слот свободен */
+    uint8_t *buf;        /* ленивый буфер BUFSIZ байт или NULL */
+    uint8_t *curp;       /* текущая позиция в буфере */
+    uint16_t level;      /* байт в буфере (смысл зависит от _F_DIROUT) */
+    int      hold;       /* байт от ungetc, EOF = пусто */
 } FILE;
 
 #define _F_READ    0x01
 #define _F_WRITE   0x02
 #define _F_APPEND  0x04
+#define _F_DIROUT  0x08  /* буфер сейчас копит запись (иначе readahead) */
 #define _F_EOF     0x10
 #define _F_ERROR   0x20
 #define _F_CONIN   0x40  /* console pseudo-stream — uses getchar() */
@@ -70,6 +91,10 @@ int    fputc (int c, FILE *fp);
 int    fgetc (FILE *fp);
 int    fputs (const char *s, FILE *fp);
 char  *fgets (char *buf, int n, FILE *fp);
+int    ungetc(int c, FILE *fp);
+
+int    fprintf (FILE *fp, const char *fmt, ...);
+int    vfprintf(FILE *fp, const char *fmt, va_list ap);
 
 size_t fread (void *ptr, size_t size, size_t nmemb, FILE *fp);
 size_t fwrite(const void *ptr, size_t size, size_t nmemb, FILE *fp);