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.