Merge branch 'mh/update-ref-batch-create-fix'
[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.