2 files changed, 29 insertions(+), 15 deletions(-)

M fs/comp/c/lib.fs
M fs/doc/cc/lib.txt

@@ 26,6 26,11 @@ $100 MemFile :new const _sfile
 : fread IO :read ;
 (S a n hdl -- )
 : fwrite IO :write ;
+(S 'a n hdl -- read-n )
+: freadbuf IO :readbuf ( 'a a? read-n ) dup if ( 'a a read-n )
+    rot> swap ! else ( 'a 0 ) nip then ;
+(S a n hdl -- written-n )
+: fwritebuf IO :writebuf ;
 (S pos hdl -- )
 : fseek File :seek ;
 (S hdl -- )

@@ 31,25 31,34 @@ int isdigit(char c)
 The I/O API is a simple layer over the system I/O described at doc/io. `hdl` is
 a regular I/O handle.
 
-char fgetc(int hdl)                    --> IO :getc
-void fputc(char c, int hdl)            --> IO :putc
-void fputback(char c, int hdl)         --> IO :putback
-char* freadline(int hdl)               --> IO :putback
-int fopen(char *path)                  --> Path :find# + Path :open
-void fread(int *addr, int n, int hdl)  --> IO :read
-void fwrite(int *addr, int n, int hdl) --> IO :write
-void fseek(int pos, int hdl)           --> File :seek
-void fclose(int hdl)                   --> IO :close
-void fputs(char *str, int hdl)         --> IO :puts
-void puts(char *str)                   --> fputs(StdOut)
+char fgetc(int hdl)                      --> IO :getc
+void fputc(char c, int hdl)              --> IO :putc
+void fputback(char c, int hdl)           --> IO :putback
+char* freadline(int hdl)                 --> IO :putback
+int fopen(char *path)                    --> Path :find# + Path :open
+void fread(int *addr, int n, int hdl)    --> IO :read
+int freadbuf(int **addr, int n, int hdl) --> IO :readbuf
+void fwrite(int *addr, int n, int hdl)   --> IO :write
+int fwritebuf(int *addr, int n, int hdl) --> IO :writebuf
+void fseek(int pos, int hdl)             --> File :seek
+void fclose(int hdl)                     --> IO :close
+void fputs(char *str, int hdl)           --> IO :puts
+void puts(char *str)                     --> fputs(StdOut)
 (see below for details about printf/scanf)
-void fprintf(... char *fmt, int hdl)   --> IO :printf
-void printf(... char *fmt)             --> fprintf(StdOut)
+void fprintf(... char *fmt, int hdl)     --> IO :printf
+void printf(... char *fmt)               --> fprintf(StdOut)
 char* sprintf(... char *fmt)
-int fscanf(char *fmt, int hdl)         --> see below
-int scanf(char *fmt)                   --> fscanf(StdIn)
+int fscanf(char *fmt, int hdl)           --> see below
+int scanf(char *fmt)                     --> fscanf(StdIn)
 int sscanf(char *fmt, char *str)
 
+### freadbuf
+
+This function is special because :readbuf returns two arguments. The return
+value of freadbuf() is "read-n", but "a" is returned through a pointer to an
+address which you supply as an argument. If :readbuf is successful, that the
+resulting address is written there. Otherwise, nothing is written.
+
 ### printf/scanf and variants
 
 fprintf behaves a bit like the standard one, but supports less formatting