blob: 8e139eb22df0f44ba0b805b374943dd5d12e8437 (
plain) (
tree)
|
|
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.
|
