1line_buffer API 2=============== 3 4The line_buffer library provides a convenient interface for 5mostly-line-oriented input. 6 7Each line is not permitted to exceed 10000 bytes. The provided 8functions are not thread-safe or async-signal-safe, and like 9`fgets()`, they generally do not function correctly if interrupted 10by a signal without SA_RESTART set. 11 12Calling sequence 13---------------- 14 15The 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 23Before exiting, the caller can use `buffer_reset` to deallocate 24resources for the benefit of profiling tools. 25 26Functions 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.