The calling program:
+ - initializes a `struct line_buffer` to LINE_BUFFER_INIT
- specifies a file to read with `buffer_init`
- - processes input with `buffer_read_line`, `buffer_read_string`,
- `buffer_skip_bytes`, and `buffer_copy_bytes`
+ - processes input with `buffer_read_line`, `buffer_skip_bytes`,
+ and `buffer_copy_bytes`
- closes the file with `buffer_deinit`, perhaps to start over and
read another file.
-Before exiting, the caller can use `buffer_reset` to deallocate
-resources for the benefit of profiling tools.
+When finished, the caller can use `buffer_reset` to deallocate
+resources.
+
+Using temporary files
+---------------------
+
+Temporary files provide a place to store data that should not outlive
+the calling program. A program
+
+ - initializes a `struct line_buffer` to LINE_BUFFER_INIT
+ - requests a temporary file with `buffer_tmpfile_init`
+ - acquires an output handle by calling `buffer_tmpfile_rewind`
+ - uses standard I/O functions like `fprintf` and `fwrite` to fill
+ the temporary file
+ - declares writing is over with `buffer_tmpfile_prepare_to_read`
+ - can re-read what was written with `buffer_read_line`,
+ `buffer_copy_bytes`, and so on
+ - can reuse the temporary file by calling `buffer_tmpfile_rewind`
+ again
+ - removes the temporary file with `buffer_deinit`, perhaps to
+ reuse the line_buffer for some other file.
+
+When finished, the calling program can use `buffer_reset` to deallocate
+resources.
Functions
---------
-`buffer_init`::
- Open the named file for input. If filename is NULL,
- start reading from stdin. On failure, returns -1 (with
- errno indicating the nature of the failure).
+`buffer_init`, `buffer_fdinit`::
+ Open the named file or file descriptor for input.
+ buffer_init(buf, NULL) prepares to read from stdin.
+ On failure, returns -1 (with errno indicating the nature
+ of the failure).
`buffer_deinit`::
Stop reading from the current file (closing it unless
Read a line and strip off the trailing newline.
On failure or end of file, returns NULL.
-`buffer_read_string`::
- Read `len` characters of input or up to the end of the
- file, whichever comes first. Returns NULL on error.
- Returns whatever characters were read (possibly "")
- for end of file.
-
`buffer_copy_bytes`::
Read `len` bytes of input and dump them to the standard output
stream. Returns early for error or end of file.
`buffer_skip_bytes`::
Discards `len` bytes from the input stream (stopping early
- if necessary because of an error or eof).
+ if necessary because of an error or eof). Return value is
+ the number of bytes successfully read.
`buffer_reset`::
Deallocates non-static buffers.