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