]>
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 | 18 | - specifies a file to read with `buffer_init` |
7e2fe3a9 JN |
19 | - processes input with `buffer_read_line`, `buffer_skip_bytes`, |
20 | and `buffer_copy_bytes` | |
3bbaec00 DB |
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 | 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`, | |
7e2fe3a9 | 40 | `buffer_copy_bytes`, and so on |
b1c9b798 JN |
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 | ||
3bbaec00 DB |
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 | |
d234f54b JN |
73 | if necessary because of an error or eof). Return value is |
74 | the number of bytes successfully read. | |
3bbaec00 DB |
75 | |
76 | `buffer_reset`:: | |
77 | Deallocates non-static buffers. |