[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:

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

`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
e5e45ca1	17	- initializes a `struct line_buffer` to LINE_BUFFER_INIT
3bbaec00 DB	18	- specifies a file to read with `buffer_init`
	19	- processes input with `buffer_read_line`, `buffer_read_string`,
	20	`buffer_skip_bytes`, and `buffer_copy_bytes`
	21	- closes the file with `buffer_deinit`, perhaps to start over and
	22	read another file.
	23
e5e45ca1 JN	24	When finished, the caller can use `buffer_reset` to deallocate
e5e45ca1 JN	25	resources.
3bbaec00	26
b1c9b798 JN	27	Using temporary files
	28	---------------------
	29
	30	Temporary files provide a place to store data that should not outlive
	31	the calling program. A program
	32
	33	- initializes a `struct line_buffer` to LINE_BUFFER_INIT
	34	- requests a temporary file with `buffer_tmpfile_init`
	35	- acquires an output handle by calling `buffer_tmpfile_rewind`
	36	- uses standard I/O functions like `fprintf` and `fwrite` to fill
	37	the temporary file
	38	- declares writing is over with `buffer_tmpfile_prepare_to_read`
	39	- can re-read what was written with `buffer_read_line`,
	40	`buffer_read_string`, and so on
	41	- can reuse the temporary file by calling `buffer_tmpfile_rewind`
	42	again
	43	- removes the temporary file with `buffer_deinit`, perhaps to
	44	reuse the line_buffer for some other file.
	45
	46	When finished, the calling program can use `buffer_reset` to deallocate
	47	resources.
	48
3bbaec00 DB	49	Functions
	50	---------
	51
cb3f87cf JN	52	`buffer_init`, `buffer_fdinit`::
	53	Open the named file or file descriptor for input.
	54	buffer_init(buf, NULL) prepares to read from stdin.
	55	On failure, returns -1 (with errno indicating the nature
	56	of the failure).
3bbaec00 DB	57
	58	`buffer_deinit`::
	59	Stop reading from the current file (closing it unless
	60	it was stdin). Returns nonzero if `fclose` fails or
	61	the error indicator was set.
	62
	63	`buffer_read_line`::
	64	Read a line and strip off the trailing newline.
	65	On failure or end of file, returns NULL.
	66
	67	`buffer_read_string`::
	68	Read `len` characters of input or up to the end of the
	69	file, whichever comes first. Returns NULL on error.
	70	Returns whatever characters were read (possibly "")
	71	for end of file.
	72
	73	`buffer_copy_bytes`::
	74	Read `len` bytes of input and dump them to the standard output
	75	stream. Returns early for error or end of file.
	76
	77	`buffer_skip_bytes`::
	78	Discards `len` bytes from the input stream (stopping early
d234f54b JN	79	if necessary because of an error or eof). Return value is
d234f54b JN	80	the number of bytes successfully read.
3bbaec00 DB	81
	82	`buffer_reset`::
	83	Deallocates non-static buffers.