Merge branch 'rs/nth-switch-code-simplification'
[git/git.git] / vcs-svn / line_buffer.txt
CommitLineData
3bbaec00
DB
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
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
24When finished, the caller can use `buffer_reset` to deallocate
25resources.
3bbaec00 26
b1c9b798
JN
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`,
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
46When finished, the calling program can use `buffer_reset` to deallocate
47resources.
48
3bbaec00
DB
49Functions
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.