]>
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 |
25 | resources. | |
3bbaec00 DB |
26 | |
27 | Functions | |
28 | --------- | |
29 | ||
30 | `buffer_init`:: | |
31 | Open the named file for input. If filename is NULL, | |
32 | start reading from stdin. On failure, returns -1 (with | |
33 | errno indicating the nature of the failure). | |
34 | ||
35 | `buffer_deinit`:: | |
36 | Stop reading from the current file (closing it unless | |
37 | it was stdin). Returns nonzero if `fclose` fails or | |
38 | the error indicator was set. | |
39 | ||
40 | `buffer_read_line`:: | |
41 | Read a line and strip off the trailing newline. | |
42 | On failure or end of file, returns NULL. | |
43 | ||
44 | `buffer_read_string`:: | |
45 | Read `len` characters of input or up to the end of the | |
46 | file, whichever comes first. Returns NULL on error. | |
47 | Returns whatever characters were read (possibly "") | |
48 | for end of file. | |
49 | ||
50 | `buffer_copy_bytes`:: | |
51 | Read `len` bytes of input and dump them to the standard output | |
52 | stream. Returns early for error or end of file. | |
53 | ||
54 | `buffer_skip_bytes`:: | |
55 | Discards `len` bytes from the input stream (stopping early | |
56 | if necessary because of an error or eof). | |
57 | ||
58 | `buffer_reset`:: | |
59 | Deallocates non-static buffers. |