Revision e293c563b00f9adfff44676d7406d40194aff228 authored by Junio C Hamano on 25 June 2014, 18:43:07 UTC, committed by Junio C Hamano on 25 June 2014, 18:43:07 UTC
We used to unconditionally disable the pager in the pager process we spawn to feed out output, but that prevented people who want to run "less" within "less" from doing so. * je/pager-do-not-recurse: pager: do allow spawning pager recursively
line_buffer.txt
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_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_copy_bytes`, 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_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). Return value is
the number of bytes successfully read.
`buffer_reset`::
Deallocates non-static buffers.
![swh spinner](/static/img/swh-spinner.gif)
Computing file changes ...