git/vcs-svn/line_buffer.txt
David Barr 3bbaec00a8 Add stream helper library
This library provides thread-unsafe fgets()- and fread()-like
functions where the caller does not have to supply a buffer.  It
maintains a couple of static buffers and provides an API to use
them.

[rr: allow input from files other than stdin]
[jn: with tests, documentation, and error handling improvements]

Signed-off-by: David Barr <david.barr@cordelta.com>
Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-08-14 19:35:37 -07:00

59 lines
1.7 KiB
Plaintext

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:
- specifies a file to read with `buffer_init`
- processes input with `buffer_read_line`, `buffer_read_string`,
`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.
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_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_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).
`buffer_reset`::
Deallocates non-static buffers.