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 - initializes a `struct line_buffer` to LINE_BUFFER_INIT 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 24When finished, the caller can use `buffer_reset` to deallocate 25resources. 26 27Using temporary files 28--------------------- 29 30Temporary files provide a place to store data that should not outlive 31the 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 46When finished, the calling program can use `buffer_reset` to deallocate 47resources. 48 49Functions 50--------- 51 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). 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 79 if necessary because of an error or eof). 80 81`buffer_reset`:: 82 Deallocates non-static buffers.