[thirdparty/git.git] / 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:

 - 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.
Commit	Line	Data
3bbaec00 DB	1	line_buffer API
	2	===============
	3
	4	The line_buffer library provides a convenient interface for
	5	mostly-line-oriented input.
	6
	7	Each line is not permitted to exceed 10000 bytes. The provided
	8	functions are not thread-safe or async-signal-safe, and like
	9	`fgets()`, they generally do not function correctly if interrupted
	10	by a signal without SA_RESTART set.
	11
	12	Calling sequence
	13	----------------
	14
	15	The calling program:
	16
	17	- specifies a file to read with `buffer_init`
	18	- processes input with `buffer_read_line`, `buffer_read_string`,
	19	`buffer_skip_bytes`, and `buffer_copy_bytes`
	20	- closes the file with `buffer_deinit`, perhaps to start over and
	21	read another file.
	22
	23	Before exiting, the caller can use `buffer_reset` to deallocate
	24	resources for the benefit of profiling tools.
	25
	26	Functions
	27	---------
	28
	29	`buffer_init`::
	30	Open the named file for input. If filename is NULL,
	31	start reading from stdin. On failure, returns -1 (with
	32	errno indicating the nature of the failure).
	33
	34	`buffer_deinit`::
	35	Stop reading from the current file (closing it unless
	36	it was stdin). Returns nonzero if `fclose` fails or
	37	the error indicator was set.
	38
	39	`buffer_read_line`::
	40	Read a line and strip off the trailing newline.
	41	On failure or end of file, returns NULL.
	42
	43	`buffer_read_string`::
	44	Read `len` characters of input or up to the end of the
	45	file, whichever comes first. Returns NULL on error.
	46	Returns whatever characters were read (possibly "")
	47	for end of file.
	48
	49	`buffer_copy_bytes`::
	50	Read `len` bytes of input and dump them to the standard output
	51	stream. Returns early for error or end of file.
	52
	53	`buffer_skip_bytes`::
	54	Discards `len` bytes from the input stream (stopping early
	55	if necessary because of an error or eof).
	56
	57	`buffer_reset`::
	58	Deallocates non-static buffers.