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_skip_bytes`, 20 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_copy_bytes`, 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_copy_bytes`:: 68 Read `len` bytes of input and dump them to the standard output 69 stream. Returns early for error or end of file. 70 71`buffer_skip_bytes`:: 72 Discards `len` bytes from the input stream (stopping early 73 if necessary because of an error or eof). Return value is 74 the number of bytes successfully read. 75 76`buffer_reset`:: 77 Deallocates non-static buffers.