vcs-svn/line_buffer.txt

line_buffer API
===============

The line_buffer library provides a convenient interface for
mostly-line-oriented input.

Each line is not permitted to exceed 10000 bytes.  The provided
functions are not thread-safe or async-signal-safe, and like
`fgets()`, they generally do not function correctly if interrupted
by a signal without SA_RESTART set.

Calling sequence
----------------

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_skip_bytes`,
   and `buffer_copy_bytes`
 - closes the file with `buffer_deinit`, perhaps to start over and
   read another file.

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`, `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
	it was stdin).  Returns nonzero if `fclose` fails or
	the error indicator was set.

`buffer_read_line`::
	Read a line and strip off the trailing newline.
	On failure or end of file, returns NULL.

`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).  Return value is
	the number of bytes successfully read.

`buffer_reset`::
	Deallocates non-static buffers.