mirror of
https://github.com/git/git
synced 2024-11-05 18:59:29 +00:00
b1c9b798a6
It can sometimes be useful to write information temporarily to file,
to read back later. These functions allow a program to use the
line_buffer facilities when doing so.
It works like this:
1. find a unique filename with buffer_tmpfile_init.
2. rewind with buffer_tmpfile_rewind. This returns a stdio
handle for writing.
3. when finished writing, declare so with
buffer_tmpfile_prepare_to_read. The return value indicates
how many bytes were written.
4. read whatever portion of the file is needed.
5. if finished, remove the temporary file with buffer_deinit.
otherwise, go back to step 2,
The svn support would use this to buffer the postimage from delta
application until the length is known and fast-import can receive
the resulting blob.
Based-on-patch-by: David Barr <david.barr@cordelta.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
82 lines
2.6 KiB
Text
82 lines
2.6 KiB
Text
line_buffer API
|
|
===============
|
|
|
|
The line_buffer library provides a convenient interface for
|
|
mostly-line-oriented input.
|
|
|
|
Each line is not permitted to exceed 10000 bytes. The provided
|
|
functions are not thread-safe or async-signal-safe, and like
|
|
`fgets()`, they generally do not function correctly if interrupted
|
|
by a signal without SA_RESTART set.
|
|
|
|
Calling sequence
|
|
----------------
|
|
|
|
The calling program:
|
|
|
|
- initializes a `struct line_buffer` to LINE_BUFFER_INIT
|
|
- specifies a file to read with `buffer_init`
|
|
- processes input with `buffer_read_line`, `buffer_read_string`,
|
|
`buffer_skip_bytes`, and `buffer_copy_bytes`
|
|
- closes the file with `buffer_deinit`, perhaps to start over and
|
|
read another file.
|
|
|
|
When finished, the caller can use `buffer_reset` to deallocate
|
|
resources.
|
|
|
|
Using temporary files
|
|
---------------------
|
|
|
|
Temporary files provide a place to store data that should not outlive
|
|
the calling program. A program
|
|
|
|
- initializes a `struct line_buffer` to LINE_BUFFER_INIT
|
|
- requests a temporary file with `buffer_tmpfile_init`
|
|
- acquires an output handle by calling `buffer_tmpfile_rewind`
|
|
- uses standard I/O functions like `fprintf` and `fwrite` to fill
|
|
the temporary file
|
|
- declares writing is over with `buffer_tmpfile_prepare_to_read`
|
|
- can re-read what was written with `buffer_read_line`,
|
|
`buffer_read_string`, and so on
|
|
- can reuse the temporary file by calling `buffer_tmpfile_rewind`
|
|
again
|
|
- removes the temporary file with `buffer_deinit`, perhaps to
|
|
reuse the line_buffer for some other file.
|
|
|
|
When finished, the calling program can use `buffer_reset` to deallocate
|
|
resources.
|
|
|
|
Functions
|
|
---------
|
|
|
|
`buffer_init`, `buffer_fdinit`::
|
|
Open the named file or file descriptor for input.
|
|
buffer_init(buf, NULL) prepares to read from stdin.
|
|
On failure, returns -1 (with errno indicating the nature
|
|
of the failure).
|
|
|
|
`buffer_deinit`::
|
|
Stop reading from the current file (closing it unless
|
|
it was stdin). Returns nonzero if `fclose` fails or
|
|
the error indicator was set.
|
|
|
|
`buffer_read_line`::
|
|
Read a line and strip off the trailing newline.
|
|
On failure or end of file, returns NULL.
|
|
|
|
`buffer_read_string`::
|
|
Read `len` characters of input or up to the end of the
|
|
file, whichever comes first. Returns NULL on error.
|
|
Returns whatever characters were read (possibly "")
|
|
for end of file.
|
|
|
|
`buffer_copy_bytes`::
|
|
Read `len` bytes of input and dump them to the standard output
|
|
stream. Returns early for error or end of file.
|
|
|
|
`buffer_skip_bytes`::
|
|
Discards `len` bytes from the input stream (stopping early
|
|
if necessary because of an error or eof).
|
|
|
|
`buffer_reset`::
|
|
Deallocates non-static buffers.
|